SAP API Style Guide conventions

Contract

Enforces the SAP API Business Hub house style on OpenAPI documents — API naming, the x-sap-* vendor extensions, operation/response wording, lifecycle metadata, and character limits. Apply whenever you write or edit an info block, an operation, a response, or deprecation metadata for a REST/OData API destined for SAP API Business Hub. These are arbitrary SAP conventions; do not substitute generic OpenAPI habits.

Rules

1. info.title (API name)

• REMOVE the word "API" — it is implied. "Custom Forms API" -> "Custom Forms".
• REMOVE a leading "SAP" prefix. "SAP Document Approval" -> "Document Approval".
• Use a NOUN PHRASE. No verb, gerund, or preposition lead: "Configuring Portal" ->

"Portal Configuration"; "Manage Invoices" -> "Invoice Management".

• Do NOT embed the protocol (REST, OData, SOAP, GraphQL) in the name.
• Do NOT embed a version (v2, OData v4) in the name — version lives in metadata.
• Use Title Case (capitalize each significant word).
• info.title must be at most 80 characters.

2. Short text (catalog tile description)

• Put the one-line tile description in the vendor extension x-sap-shortText.
• NEVER use summary, shortDescription, tagline, or info.description for the

tile text — those are ignored by the Business Hub tile renderer.

• x-sap-shortText must be at most 180 characters.
• It is distinct from info.description (the long description), which may run to ~2

sentences / 1024 chars.

3. Operation summary and description

• summary: action-oriented, starts with a verb (Creates, Retrieves, Updates,

Deletes, Searches), no trailing period (preferred), at most 255 characters.

• description: begins with a third-person singular present-tense verb — Creates,

Retrieves, Updates, Deletes, Returns, Replaces, Cancels.

• NEVER begin a description with "This operation", "This endpoint", "This method",

or "The API".

• NEVER use the second person (you, your).
• Do NOT repeat the summary verbatim in the description; the description adds detail

(side effects, constraints, prerequisites). Omit description entirely if it would only restate the summary.

4. Response descriptions

• State the specific outcome, not the generic HTTP reason phrase.
• 204 -> "The product was deleted." NOT "No Content".
• 404 -> "The requested product does not exist." NOT "Not Found".
• 201 -> "The sales order was created." NOT "Created".
• 409 -> "An employee with that ID already exists." NOT "Conflict".

5. Lifecycle / deprecation (x-sap-stateInfo)

• Mark lifecycle with the vendor extension x-sap-stateInfo — NOT the bare OpenAPI

deprecated: true flag (the Business Hub reads x-sap-stateInfo, not deprecated).

• x-sap-stateInfo.state is exactly one of: beta, active, deprecated,

decommissioned. The fully-retired state is decommissioned — never retired, sunset, removed, obsolete, or eol.

• A deprecated API MUST also set:
• deprecationDate — ISO 8601 YYYY-MM-DD.
• successorApi — the name of the replacement API.
• optional: plannedDecommissionDate (YYYY-MM-DD), moreInformation (migration URL).
• active is the default; you may state it explicitly but it is not required.
• Timeline: a deprecated API must remain available at least 12 months after the

deprecation date before it can be decommissioned, and an API's total lifespan (active + deprecated) should be at least 24 months.

6. Other vendor fields & naming

• x-sap-apiType is "REST" or "OData" (this is where the protocol belongs — never

the title).

• Field/parameter names: camelCase for REST (employeeId), PascalCase for OData

(EmployeeId); never snake_case or kebab-case for JSON fields.

7. Character limits (memorize)

| Element | Limit | |---|---| | info.title | 80 | | x-sap-shortText | 180 | | Package short description | 250 | | Operation summary | 255 | | description | 1024 |

Worked examples

Rule 1 — title strips "API":

• BEFORE: title: "Custom Forms API"
• AFTER: title: "Custom Forms"

Rule 1 — title strips "SAP":

• BEFORE: title: "SAP Document Approval"
• AFTER: title: "Document Approval"

Rule 1 — gerund/verb -> noun phrase:

• BEFORE: title: "Configuring Customer Portals"
• AFTER: title: "Portal Configuration"

Rule 1 — protocol + version in name:

• BEFORE: title: "SAP Sales Order OData API v4"
• AFTER: title: "Sales Order" (protocol -> x-sap-apiType: "OData", version -> version:)

Rule 1 — over the 80-char limit:

• BEFORE: title: "Advanced Real-Time Inventory and Warehouse Stock Level Monitoring and Replenishment Management for SAP S/4HANA"
• AFTER: title: "Inventory and Replenishment Management" (38 chars)

Rule 2 — tile text in the right field:

• BEFORE: info: { summary: "Manage employee leave requests" }
• AFTER: info: { x-sap-shortText: "Submit, approve, and track employee leave requests with policy validation" }

Rule 3 — operation description:

• BEFORE: description: "This endpoint lets you create a new customer record."
• AFTER: description: "Creates a customer record and emits a CustomerCreated event; returns 201 with a Location header."

Rule 3 — no summary repetition:

• summary: "Create a new user"
• BEFORE: description: "Create a new user."
• AFTER: description: "Creates a user account, sends the activation email, and assigns the default role."

Rule 4 — specific response outcome:

• BEFORE: responses: { '204': { description: "No Content" } }
• AFTER: responses: { '204': { description: "The product was deleted." } }

Rule 5 — deprecate, not deprecated: true:

• BEFORE:

yaml info: title: "Custom Forms" deprecated: true

• AFTER:

yaml info: title: "Custom Forms" x-sap-stateInfo: state: deprecated deprecationDate: "2026-06-26" successorApi: "Custom Forms v2" plannedDecommissionDate: "2027-06-26"

Rule 5 — beta service:

• BEFORE: info: { title: "Shipment Tracking API", x-beta: true }
• AFTER:

yaml info: title: "Shipment Tracking" x-sap-stateInfo: state: beta

Rule 5 — decommission term:

• BEFORE: state: retired
• AFTER: state: decommissioned

Edge cases & exceptions

• "SAP" inside the name, not a prefix: strip only the leading contextual SAP.

A product name that genuinely contains it for disambiguation may keep it, but default to removing it — "SAP Travel Management" -> "Travel Management".

• Acronyms that read as the word "API": keep legitimate domain acronyms; only drop

the literal word API/APIs. "OAuth" stays; "Forms API" loses API.

• Title at exactly 80 chars: 80 is allowed (the limit is inclusive); 81 is not.
• No extra description needed: if the summary already says everything, OMIT

description rather than padding it — an empty description beats a restated one.

• Deprecated but no successor yet: the policy still requires successorApi; if there

is genuinely no successor, the API is heading to decommissioned, not deprecated.

• active is implicit: you do not need x-sap-stateInfo at all for a healthy API; add

it only to declare beta, deprecated, or decommissioned (or to be explicit).

• Date format: dates are always ISO YYYY-MM-DD strings, quoted in YAML; never

01/15/2026 or Jan 15 2026.

Do / Don't

• DON'T put API, SAP, a protocol, or a version in info.title. ALWAYS use a bare

Title-Case noun phrase.

• DON'T write description: "This operation creates…". ALWAYS lead with the bare

third-person verb "Creates…".

• DON'T address the reader as you. ALWAYS describe what the operation does.
• DON'T put the tile text in summary/description. ALWAYS use x-sap-shortText.
• DON'T deprecate with deprecated: true. ALWAYS use x-sap-stateInfo.state: deprecated

plus deprecationDate and successorApi.

• DON'T name the retired state retired/sunset/removed. ALWAYS use decommissioned.
• DON'T echo the generic HTTP phrase in a response. ALWAYS state the concrete outcome.

Common mistakes

The bare base model defaults to these — all wrong for SAP:

• Keeps "… API" or a "SAP " prefix in the title because that reads natural.
• Names the API with a gerund ("Managing Orders") or embeds OData/v2.
• Writes description: "This endpoint allows you to…" (second person + "This endpoint").
• Copies the summary into description verbatim.
• Labels a 204 response "No Content" and a 404 "Not Found" (the HTTP reason phrase).
• Reaches for OpenAPI's standard deprecated: true instead of x-sap-stateInfo.
• Invents state: "retired" / "sunset" instead of decommissioned.
• Puts the tile line in summary or info.description instead of x-sap-shortText.
• Forgets the 80-char title / 180-char shortText ceilings.

Quick checklist

• ] Title: no API, no SAP, no protocol, no version, noun phrase, Title Case, ≤80.
• ] Tile line in x-sap-shortText, ≤180.
• ] Operation description starts with a third-person verb; no This …, no you.
• ] description adds detail beyond summary (or is omitted).
• ] Response descriptions state the concrete outcome, not the HTTP phrase.
• ] Lifecycle via x-sap-stateInfo; state ∈ {beta, active, deprecated, decommissioned}.
• ] Deprecated has deprecationDate (YYYY-MM-DD) + successorApi; ≥12 months notice.