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

Lesson 1 of 5

API-first

9 min

Listen to this lesson

0:00 / 6:17

Great Lakes Fleet Services, Contoso Motor Co.'s largest fleet customer, wants its maintenance planners to see order status for alternators without calling Maria in order-to-cash. Five years ago Contoso would have built a nightly file. Today the request is for an API: a stable, documented, secured endpoint the customer's own portal can call whenever a planner opens an order. How Contoso designs, exposes and governs that API is what this course is about.

What API-first means

API-first means you design the interface contract before you build the implementation, and you treat the API as a product with consumers, versions and a lifecycle. The contract is usually written in the OpenAPI Specification, an open standard that describes an HTTP API's paths, operations, parameters, payloads and responses in a language-neutral way. Consumers can start building against the contract while the provider builds the backend, and testers can derive tests from it.

Contract first: once the OpenAPI description is agreed, Great Lakes, Contoso's builders and Priya's testers all work from it in parallel.
The Sign-Off Table · thesignofftable.com/academy/sap-int-204
  1. DesignContract agreedOrder status API described in OpenAPI and reviewed with Great Lakes Fleet Services.
  2. BuildBackend and proxyS/4HANA service selected; API proxy created with policies.
  3. TestContract and policy testsResponses checked against the contract; keys, quotas and errors tested.
  4. PublishProduct in the developer hubCustomer developers subscribe and receive keys.
  5. RunMonitor and evolveAnalytics watched; new versions released without breaking v1.
The API lifecycle for Contoso's order status API.
The Sign-Off Table · thesignofftable.com/academy/sap-int-204

Where API Management sits

SAP describes API Management as the capability in SAP Integration Suite for creating, publishing, monitoring and securing APIs, and as a central building block of an API-first architecture. It does not replace the backend or the integration logic. It sits in front of them as a governed façade: consumers call a proxy URL under Contoso's own domain, policies enforce security and traffic rules, and the proxy forwards the call to the real service.

ConsumersGreat Lakes Fleet Services' portal, Contoso's own mobile app, internal analytics
Developer hubWhere consumer developers discover products, read documentation and get keys
API Management proxy layerAPI proxies with security, traffic and mediation policies; analytics on every call
Integration and servicesCloud Integration flows where orchestration or mapping is needed
BackendsSAP S/4HANA OData and SOAP services on CMP, reached through Cloud Connector; other systems
API Management as a governed layer between consumers and Contoso's backends.
The Sign-Off Table · thesignofftable.com/academy/sap-int-204

For SAP S/4HANA, start from the APIs SAP already releases. The SAP Business Accelerator Hub (api.sap.com) documents SAP's published APIs, including the sales order APIs, with their operations, fields and, for many, a sandbox. A released API is supported across upgrades; a custom service built for one consumer is something Kenji's team will own forever. Contoso's rule: use a released API where one fits, and put the consumer-specific shape in the proxy or an integration flow, not in custom ABAP.

A full contract defines every outcome a consumer can meet, not just the 200; each branch is agreed up front and becomes a test case.
The Sign-Off Table · thesignofftable.com/academy/sap-int-204

What would you do?

Great Lakes Fleet Services asks for order status by their own purchase order number. Kenji proposes a custom OData service in S/4HANA built exactly to their format. What should Theo, the integration lead, recommend first?

Key points
  • API-first means agreeing the contract, usually in OpenAPI, before building the implementation.
  • API Management is a governed façade in front of backends and integration flows, not a replacement for them.
  • Prefer SAP's released APIs from the SAP Business Accelerator Hub over custom services.
  • Design error responses as part of the contract.

Check your understanding · not graded

Lesson check

  1. 1. Which open standard is commonly used to describe an HTTP API contract?

  2. 2. What role does API Management play in front of S/4HANA services?

  3. 3. Why prefer an SAP released API over a custom service for an external consumer?

  4. 4. In API-first design, when are error responses agreed?