OData V4 Part 1: The OData V4 Contract — Metadata, Keys, Navigation, Queries

📌 KEY POINTS
✅ $metadata is the contract: entity types, keys, properties, navigation, actions.
✅ Query options shape the response: $select, $filter, $orderby, $top/$skip, $count, $expand.
✅ Draft-enabled RAP entities have a second key: IsActiveEntity.
💡 Always $select only the fields you need — it is the simplest performance win.

━━━━━━━━━━━━━━━━━━━━
▶ WHAT THIS SERIES COVERS

• Part 1 — the OData V4 contract (this lesson)
• Part 2 — publishing a RAP service with an OData V4 binding
• Part 3 — testing CRUD requests, payloads and responses
• Part 4 — actions, functions and batch
• Part 5 — troubleshooting HTTP errors
• Part 6 — ETags and optimistic concurrency

━━━━━━━━━━━━━━━━━━━━
▶ WHAT ODATA IS
OData is a standard REST protocol for typed business data over HTTP. RAP generates the OData service from your projections and behavior, so you do not write HTTP handlers — but you must understand the contract to test, integrate and troubleshoot.

━━━━━━━━━━━━━━━━━━━━
▶ 1. THE SERVICE ROOT AND SERVICE DOCUMENT
A RAP OData V4 UI service URL looks like:
/sap/opu/odata4/sap/zui_purchreq_o4/srvd/sap/zui_purchreq/0001/

• zui_purchreq_o4 — the binding, zui_purchreq — the service definition, 0001 — the service version.

GET on the root returns the service document: the list of entity sets.\n\n━━━━━━━━━━━━━━━━━━━━\n▶ 2. $METADATA — THE CONTRACT\nGET …/$metadata returns XML describing:

• EntityType — structure: Property (name, type, nullable, maxLength), Key.
• EntitySet — the collection you query (PurchaseRequest).
• NavigationProperty — relationships (_Item) with NavigationPropertyBinding to target sets.
• Action / Function — operations (approve).
• Annotations — UI and semantics vocabularies (for Fiori).

Every client relies on this; changing it can break clients (Service Definitions Part 3).

━━━━━━━━━━━━━━━━━━━━
▶ 3. KEYS AND ENTITY ADDRESSING

• Single entity: …/PurchaseRequest(RequestUUID=<uuid>)
• With draft: …/PurchaseRequest(RequestUUID=<uuid>,IsActiveEntity=true) — active version; false = draft.
• Navigation: …/PurchaseRequest(…)/_Item

━━━━━━━━━━━━━━━━━━━━
▶ 4. QUERY OPTIONS

• $select=RequestID,Description — only these properties.
• $filter=Status eq 'S' and TotalAmount gt 1000 — operators: eq, ne, gt, ge, lt, le, and, or, not; functions: contains(Description,'chair'), startswith(…).
• $orderby=CreatedAt desc
• $top=20&$skip=40 — paging.
• $count=true — total number of matching rows in the response (@odata.count).
• $expand=_Item($select=ItemNo,Quantity;$filter=Quantity gt 5) — include related entities, with nested options.
• $search=chair — free-text search (if the entity is searchable).

━━━━━━━━━━━━━━━━━━━━
▶ 5. THE JSON RESPONSE
{ "@odata.context": "…$metadata#PurchaseRequest", "@odata.count": 57, "value": [ { "RequestID": "4711", … } ] }
Single entities return the object directly, with "@odata.etag" if an ETag is defined (Part 6).

━━━━━━━━━━━━━━━━━━━━
▶ V4 VS V2 IN ONE MINUTE
V4 is the current standard for RAP: JSON by default, richer query syntax (nested $expand options), cleaner actions/functions, better batch. V2 remains for older clients (OData V2 topic).

━━━━━━━━━━━━━━━━━━━━
▶ STEP BY STEP

1. Open the service binding, copy the service URL, append $metadata.
2. Find the EntityType PurchaseRequestType, its keys and the _Item navigation.
3. Run the queries in the code example in a browser or REST client.

✅ CHECKPOINT: you can read $metadata and write any read query by hand.

A reporting tool pulled purchase requests via OData without $select and with $expand=_Item on every call. Each response contained all header fields plus all items, and nightly extraction took hours and sometimes timed out.
After reading the $metadata with the integration team, they changed the calls to $select only the six needed fields, filtered on LastChangedAt for delta loads, paged with $top/$skip, and expanded items only when needed. Extraction time fell to minutes, and the load on the backend dropped accordingly.

• Querying without $select and transferring every field.
• Forgetting IsActiveEntity for draft-enabled entities and getting "not found".
• Expanding to-many navigation everywhere.
• Paging without a stable $orderby.
• Treating $metadata as optional instead of the contract.
• Using V2 syntax (e.g. substringof) in V4 requests.

• Start every integration by reading $metadata.
• Always $select; filter server-side; page with $top/$skip and $orderby.
• Use $count=true for UIs that show totals.
• Use nested $expand options to limit expanded data.
• Use V4 for new RAP services; V2 only for legacy clients.

Questions: "What is in OData $metadata?", "Explain $select, $filter and $expand", "How do you address a draft instance in OData V4?"
Strong answer: $metadata defines entity types, keys, properties, entity sets, navigation, actions and annotations — the contract. Query options: $select for fields, $filter with operators and functions, $orderby, $top/$skip paging, $count, $expand with nested options, $search. Draft entities include IsActiveEntity in the key. Mention the RAP V4 URL anatomy (binding, service definition, version).