OData V4 Part 4: Actions, Functions and Batch Processing

📌 KEY POINTS
✅ Actions change data → POST; functions only read → GET.
✅ Bound actions are called on an entity: …/PurchaseRequest(…)/<namespace>.approve.
✅ $batch bundles requests; a change set is processed atomically (all or nothing).
💡 The exact action name including namespace is in $metadata — copy it from there.

━━━━━━━━━━━━━━━━━━━━
▶ WHERE WE ARE
Parts 1–3 covered reading and CRUD. Business APIs need commands (approve, reject, copy) and multi-step requests. This part shows how RAP operations appear in OData V4.

━━━━━━━━━━━━━━━━━━━━
▶ 1. ACTIONS (CHANGE DATA)

• Declared in the BDEF and used in the projection BDEF ("use action approve;").
• Bound action (instance action): POST on the entity, followed by the qualified action name. In RAP V4 services the name is namespaced, e.g. com.sap.gateway.srvd.zui_purchreq.v0001.approve — check $metadata.
• Result: the returned entity (for "result [1] $self") in the response body.
• Static actions are bound to the entity collection: POST …/PurchaseRequest/<namespace>.createFromTemplate.
• Factory actions return the created instance.

━━━━━━━━━━━━━━━━━━━━
▶ 2. ACTIONS WITH PARAMETERS
Parameters from the abstract entity (e.g. ZD_RejectReason) are sent as JSON body: { "Reason": "Budget exceeded" }.

━━━━━━━━━━━━━━━━━━━━
▶ 3. FUNCTIONS (READ ONLY)
Declared as "function" in the BDEF; called with GET and parameters in parentheses: GET …/PurchaseRequest(…)/<namespace>.getApprovalLevel().

━━━━━━━━━━━━━━━━━━━━
▶ 4. DRAFT ACTIONS OVER ODATA
For draft-enabled UI services:

• Edit: POST on the active instance …(IsActiveEntity=true)/<ns>.Edit with { "PreserveChanges": true } → returns the draft.
• Prepare and Activate: POST on the draft instance …(IsActiveEntity=false)/<ns>.Prepare / <ns>.Activate.
• Discard: DELETE on the draft instance.

Fiori Elements does all of this automatically; you need it for tests and custom clients.\n\n━━━━━━━━━━━━━━━━━━━━\n▶ 5. $BATCH AND CHANGE SETS\nPOST …/$batch sends several requests in one HTTP call.

• Requests in the same change set (atomicityGroup in JSON batch) are executed in one RAP transaction: either all succeed or none is saved.
• Read requests are outside change sets.
• Fiori Elements sends almost everything via $batch.
• Use change sets when a client must create a header and then call an action on it atomically; alternatively use a deep create plus a separate action call.

⚠️ WATCH OUT: an error in one change set rolls back that change set only; other change sets in the same batch can still succeed.

━━━━━━━━━━━━━━━━━━━━
▶ 6. RESPONSES AND ERRORS

• 200/201 with the result, or 204 without content.
• Business errors from RAP (FAILED/REPORTED) arrive as 4xx with an error object; messages are in "error.details" (Part 5).

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

1. Look up the action and function names in $metadata.
2. Call approve on a submitted request (active instance).
3. Call reject with a reason.
4. Build a JSON batch with one change set: create request + create item (code example).

✅ CHECKPOINT: you can call every RAP operation over HTTP.

A partner system created purchase requests and then called approve in two separate HTTP calls. When approve failed (e.g. missing budget), the request remained unapproved, and the partner created a new one on retry — producing duplicates.
The team changed the integration: the partner sends a JSON $batch with one change set (create + approve via a dependent request), or uses a deep create followed by a status check. Failed approvals now roll back the creation, and retries no longer create duplicates.

• Calling actions with GET or functions with POST.
• Guessing the action name instead of copying the namespaced name from $metadata.
• Calling draft actions on the wrong instance (active vs draft).
• Expecting all change sets in a batch to be one transaction.
• Ignoring error details returned for failed actions.
• Using UI (draft) services for integrations that need atomic create-and-act.

• Read action/function names and parameters from $metadata.
• Use change sets when several steps must be atomic.
• Return results from actions so clients need no extra read.
• Use Web API services without draft for integrations.
• Keep request collections (Postman/REST client) under version control.

Questions: "How is a RAP action called over OData V4?", "Action vs function?", "What is a change set in $batch?"
Strong answer: bound actions via POST on the entity URL with the namespaced action name (from $metadata), parameters as JSON body; functions via GET; draft actions Edit/Prepare/Activate and DELETE for discard; $batch bundles requests, change sets (atomicityGroup) run as one RAP transaction — all or nothing — while separate change sets are independent.