Now accepting guest editorial from SAP, Oracle, Workday and ServiceNow practitioners.Pitch a guide
The Sign-Off Table

Lesson 1 of 5

OData concepts

9 min

Listen to this lesson

0:00 / 5:40

OData (Open Data Protocol) is an open standard, maintained at OASIS, for reading and changing data over HTTP in a REST style. SAP uses it everywhere: every SAP Fiori app talks to its back end through OData, and many of SAP S/4HANA's released APIs are OData services. If you integrate, extend or test SAP S/4HANA, OData is the protocol you will meet most often.

At Contoso Motor Co., the FleetLink customer portal lets fleet customers such as Great Lakes Fleet Services see their orders and deliveries. After the conversion to SAP S/4HANA, FleetLink reads sales orders through a released OData API instead of the custom RFC calls it used against ECC. Kenji, the ABAP development lead, and Theo, the integration lead, own the change; Priya's team tests it.

The building blocks

ServiceA published endpoint with a root URL, for example a sales order API
Service document and $metadataThe service document lists the entity sets; $metadata describes every type, property, key and relationship
Entity setA collection you can query, such as sales orders (A_SalesOrder)
Entity type and keyThe structure of one record, such as a sales order, identified by its key, the order number
Properties and navigationFields such as SoldToParty, and navigation properties to related entities, such as the order's items
The parts of an OData service, from the endpoint down to fields and relationships.
The Sign-Off Table · thesignofftable.com/academy/sap-int-202

The $metadata document is the contract. It is machine-readable XML that names every entity type, its key, its properties with data types and lengths, and its navigation properties. Client developers generate code from it, and testers use it to know exactly which fields and operations the service offers. When an upgrade changes $metadata in an incompatible way, clients break.

Part of the contract that $metadata describes for API_SALES_ORDER_SRV: entity types with keys, and navigation properties that link the header to its items and partners.
The Sign-Off Table · thesignofftable.com/academy/sap-int-202

Addressing and query options

Everything in OData is a URL. The service root plus an entity set returns a collection; adding a key in parentheses returns one entity; adding a navigation property returns related data. Query options, which start with $, shape the result:

OptionDoesExample from FleetLink
$filterRestricts the result by a condition$filter=SoldToParty eq '17100001' (Great Lakes Fleet Services)
$selectReturns only the listed properties$select=SalesOrder,TotalNetAmount,OverallSDProcessStatus
$expandIncludes related entities inline$expand=to_Item to get the items with each order
$orderbySorts the result$orderby=CreationDate desc
$top / $skipPages through large results$top=50&$skip=100 for the third page of 50
$countReturns or includes the number of matching entitiesV4: $count=true; V2 uses /$count or $inlinecount=allpages

Common OData query options. Which options a service supports is stated in its documentation and metadata.

Changing data

OData maps create, read, update and delete to HTTP methods. GET reads. POST to an entity set creates an entity and, on success, returns 201 Created. PATCH updates only the properties you send; the OData standard prefers it for updates, while PUT replaces the entity (OData V2 services also accept MERGE, an older form of partial update). DELETE removes an entity and returns 204 No Content. A $batch request bundles several operations in one HTTP call; operations inside a change set succeed or fail together.

Inside a $batch change set, a header and its item are created together or not at all, so a client never sees half an order.
The Sign-Off Table · thesignofftable.com/academy/sap-int-202
TopicOData V2OData V4
Standard statusOlder version; still very common in SAPCurrent OASIS standard version
Default payloadAtom XML or JSON (request JSON with $format=json)JSON
Partial updateMERGE or PATCHPATCH
Counting/$count and $inlinecount$count
Operations beyond CRUDFunction importsActions and functions, bound or unbound
In SAP S/4HANAMany established released APIs and SAP Gateway Service Builder servicesNewer released APIs and the default for new RAP services
OData V2 and V4 at a glance. Check each service's version before writing a client or a test.
The Sign-Off Table · thesignofftable.com/academy/sap-int-202

What would you do?

FleetLink loads Great Lakes' order list slowly. The developer's request is <code>GET .../A_SalesOrder?$expand=to_Item</code> with no other options. Which change helps most?

Key points
  • OData is an open REST protocol; SAP Fiori and many SAP S/4HANA APIs use it.
  • Services expose entity sets of typed entities with keys, properties and navigation; $metadata is the contract.
  • Query options such as $filter, $select, $expand, $top and $skip shape reads.
  • POST creates, PATCH updates, DELETE removes; $batch change sets succeed or fail together.

Check your understanding · not graded

Lesson check

  1. 1. Which document describes every entity type, key and property of an OData service?

  2. 2. Which query option returns only the fields you list?

  3. 3. What does a successful POST to an entity set normally return?

  4. 4. What is true of operations inside one $batch change set?