RAP / CDS / ODataintermediate

Service Definitions Part 3: API Boundary, Naming and Versioning

Key takeaway

Treat a service definition as a contract: stable business names, clear naming conventions, compatible vs breaking changes, and versioning services without breaking existing consumers.

Explanation

📌 KEY POINTS
✅ Aliases, entity sets, fields and actions are the contract consumers code against.
✅ Adding is usually compatible; removing, renaming or making things mandatory is breaking.
✅ Breaking changes → new service version, old version stays until consumers migrate.
💡 Agree naming conventions (ZUI_, ZAPI_, _O4, _O2) before the first service.

━━━━━━━━━━━━━━━━━━━━
▶ WHERE WE ARE
Part 2 built services by capability. Once a service is consumed, every change affects someone. This part is about keeping services stable.

━━━━━━━━━━━━━━━━━━━━
▶ 1. NAMING CONVENTIONS

Service definition: ZUI_<OBJECT> for UI, ZAPI_<OBJECT> for APIs.
Service binding: definition name + suffix: _O4 (OData V4), _O2 (OData V2); for APIs e.g. ZAPI_<OBJECT>_O4.
Aliases: singular business nouns in CamelCase (PurchaseRequest, PurchaseRequestItem).
Actions and fields: business names (approve, RequestID), never table column names.

━━━━━━━━━━━━━━━━━━━━
▶ 2. WHAT IS PART OF THE CONTRACT
Entity set names, entity and property names, keys, navigation properties, actions/functions and their parameters, and behavior (which operations are allowed, which fields are mandatory or read-only).

━━━━━━━━━━━━━━━━━━━━
▶ 3. COMPATIBLE CHANGES (USUALLY SAFE)

New optional fields.
New entity sets or navigation properties.
New actions or functions.
New validations that do not reject data valid before.

━━━━━━━━━━━━━━━━━━━━
▶ 4. BREAKING CHANGES

Removing or renaming an entity set, field, key or action.
Changing a field from optional to mandatory, or writable to read-only.
Changing data types, lengths or action parameters.
Changing semantics (e.g. an amount now net instead of gross).

━━━━━━━━━━━━━━━━━━━━
▶ 5. VERSIONING
For breaking changes, create a new service version and keep the old one:

In RAP, an OData V4 service binding can hold multiple service versions (e.g. 0001, 0002), each based on its own service definition; the version appears in the URL.
Consumers migrate at their own pace; you retire the old version with notice.
For UI services consumed only by your own Fiori app, you can often change in place and redeploy the app together — the contract matters most for external consumers.

⚠️ WATCH OUT: whether and how multiple versions are available depends on your release and binding type — check in ADT before planning.

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

Document your naming conventions in the project wiki.
For each change request, classify: compatible or breaking.
For breaking changes on APIs: create a new service definition (e.g. ZAPI_PURCHREQ_V2), add it as a new version in the binding, communicate, migrate, retire.

✅ CHECKPOINT: you can change services without surprising consumers.

Code example

ABAP Code

// ===== Version 1 (in production, used by an external system) =====@EndUserText.label: 'Purchase Request API v1'define service ZAPI_PURCHREQ {  expose ZA_PurchReq     as PurchaseRequest;  expose ZA_PurchReqItem as PurchaseRequestItem;} // ===== Version 2: breaking change (CostCenter now mandatory, field renamed) =====@EndUserText.label: 'Purchase Request API v2'define service ZAPI_PURCHREQ_V2 {  expose ZA_PurchReq_V2     as PurchaseRequest;  expose ZA_PurchReqItem_V2 as PurchaseRequestItem;} // Binding ZAPI_PURCHREQ_O4 (OData V4 - Web API)//   Service version 0001 -> ZAPI_PURCHREQ      (existing consumers)//   Service version 0002 -> ZAPI_PURCHREQ_V2   (new consumers, migration)//   .../srvd_a2x/sap/zapi_purchreq/0001/PurchaseRequest//   .../srvd_a2x/sap/zapi_purchreq/0002/PurchaseRequest// (exact URL pattern and multi-version support: check your binding in ADT) // ===== Change classification =====// COMPATIBLE : + optional field Priority, + action cancel, + new entity Attachment// BREAKING   : - field Remark, rename Supplier->Vendor, optional->mandatory,//              changed action parameter, changed amount semantics

Real project scenario

A developer renamed the field "Remark" to "Comment" in an API projection because it "sounded better". The next morning, an external procurement system's nightly import failed, and hundreds of requests were not transferred.
The rename was rolled back. The team introduced a rule: API services are changed only compatibly in place; breaking changes need a new service version with a migration period. A simple checklist in the pull request template now asks "compatible or breaking?".

Common mistakes

Renaming fields or aliases in consumed services.
Making optional fields mandatory in place.
No naming conventions, so services are hard to find.
Assuming only external APIs need stability (internal apps break too).
Removing old versions without notice.

Best practices

Fix naming conventions at project start.
Classify every change as compatible or breaking.
Version breaking changes and support old versions for a migration period.
Keep API projections separate from UI projections.
Document each service's contract and consumers.

Interview angle

Questions: "Which changes to an OData service are breaking?", "How do you version RAP services?", "What naming conventions do you use?"
Strong answer: removing/renaming entities, fields or actions, making fields mandatory or read-only, changing types or parameters are breaking; additions are usually compatible. Breaking changes get a new service definition added as a new service version in the binding, with a migration period. Mention ZUI_/ZAPI_ and _O4/_O2 conventions.

Practice this lesson

Quick check

1. Which change to a consumed API service is compatible?

2. One service is shared by an internal UI and a partner integration. UI changes keep breaking the partner. What should the team do?

3. A project exposed base interface entities directly in its services. What is the main risk?

Interview questions

1. A developer renamed a field in an API projection and an external import failed overnight. What process changes do you introduce?

Answer it in your own words first, then compare.

2. Which changes to a consumed RAP service are breaking, and how do you handle them?

Answer it in your own words first, then compare.

Practice more with Interview AI →

Reference-verified: the steps are checked against official SAP documentation and tutorials, and object and field names in the sample code are checked for consistency. The code has not been compiled or run on an SAP system by ERPClimb. Syntax marked release-dependent varies by SAP release, so check it in your own system.