Lesson 1 of 6
Anatomy of an SAP OData call
10 min
Listen to this lesson
Course sap-tst-209 showed what an OData response means to a tester; sap-int-202 showed how services are built and activated. This course is the hands-on part: you send the calls yourself. Any HTTP client works. Postman, Bruno and curl are common choices, and nothing in the course depends on one of them. What matters is that you can read every part of a request and predict the response before you send it.
The parts of a URL
| Part | Example (OData V2) | What it tells you |
|---|---|---|
| Host | https://sandbox.api.sap.com/s4hanacloud or your system's host | Which system answers; the sandbox prefix differs from a real system |
| Service root | /sap/opu/odata/sap/API_BUSINESS_PARTNER | V2 services on SAP Gateway live under /sap/opu/odata/; V4 services under /sap/opu/odata4/ |
| Entity set | /A_BusinessPartner | The collection you read or write |
| Key | ('17100001') | One entity; key fields and quoting come from the metadata |
| Navigation | /to_BusinessPartnerAddress | A related collection, defined as a navigation property |
| Query options | ?$select=BusinessPartner,BusinessPartnerFullName&$top=5 | Shape and size of the result |
Reading a Business Partner API URL from left to right.
Read $metadata before anything else
Every OData service describes itself at $metadata. It lists the entity types, their key fields, property types and lengths, which properties may be filtered or sorted, the navigation properties and, for V2 services from SAP Gateway, SAP annotations such as sap:creatable, sap:updatable and sap:filterable. A tester who reads the metadata first avoids half of the usual mistakes: filtering on a property that is not filterable, sending a 12-character value into a 10-character field, or expecting an update on a read-only property to work.
OData V2 and V4 side by side
| Topic | OData V2 (for example API_BUSINESS_PARTNER) | OData V4 (for example Sales Order (A2X), CE_SALESORDER_0001) |
|---|---|---|
| Path on SAP Gateway | /sap/opu/odata/sap/<service> | /sap/opu/odata4/... (service group, repository, service, version) |
| JSON envelope | Result under d, collections under d.results | Collections under value; annotations such as @odata.etag |
| Count | $inlinecount=allpages or /$count | $count=true or /$count |
| Partial update | MERGE (or PATCH where supported) | PATCH |
| Next page link | __next | @odata.nextLink |
| Substring filter | substringof('x',Field) | contains(Field,'x') |
Setting up the sandbox
- Open the SAP Business Accelerator Hub (api.sap.com) and sign in with an SAP account.
- Search for Business Partner (A2X), the API_BUSINESS_PARTNER service for SAP S/4HANA Cloud, and open it.
- Choose Show API Key and copy your personal key. Treat it like a password: do not paste it into shared files or screenshots.
- Open the API reference or configuration details and copy the sandbox URL.
- In your HTTP client, create a GET request to the sandbox URL plus
/A_BusinessPartner?$top=3, add the headerAPIKeywith your key andAccept: application/json, and send it. - Check the result: status 200, a JSON body with three business partners, and response headers you can inspect.
Reading your first response
Send GET /A_BusinessPartner?$top=3 to the sandbox and look at the JSON before you look at anything else. In a V2 service everything sits under d, and a collection is the array d.results. Each entry carries a __metadata object with its uri (the canonical URL of that entity, which you can call directly), its type and, for services that use them, its etag. Navigation properties you did not expand appear as __deferred objects holding a URL: the data is not there, only the address where it can be fetched. Dates in V2 JSON look like /Date(1767225600000)/, milliseconds since 1970; V4 uses ISO dates such as 2026-01-01.
| Status on a read | Meaning | First thing to check |
|---|---|---|
| 200 OK | The request worked; the data may still be wrong or incomplete | Business values and next links |
| 400 Bad Request | Syntax error in the URL or query options | Quotes, property names, encoding |
| 401 Unauthorized | No valid credentials or API key | Header name and key or user |
| 404 Not Found | Wrong path, inactive service or a key that does not exist | Service root, key format, client |
Read responses and what to check first.
Two more requests are worth sending once on any new service. GET on the service root returns the service document: the list of entity sets the service exposes. GET $metadata returns the model. Save both with the date and the system: after an upgrade, comparing the saved metadata with the new one is the fastest way to see what changed in the API your tests depend on.
What would you do?
Wei asks you to prove that Great Lakes Fleet Services (business partner 17100001) has the customer role in CMQ. You have the sandbox working and a communication user for CMQ. What is the best first request?
- Read a URL as host, service root, entity set, key, navigation and query options.
- Read $metadata first: keys, types, lengths and what is filterable or updatable.
- V2 and V4 differ in path, JSON envelope, count, paging links and filter functions.
- The Accelerator Hub sandbox uses an APIKey header and is read-only; writes need a test system.
Check your understanding · not graded
Lesson check
1. Where do V2 services on SAP Gateway usually live?
2. What should you read first to know which properties can be filtered?
3. Which header does the Accelerator Hub sandbox expect?
4. Why can a test pass in the sandbox but fail on CMQ?