Core Principles

The principles in this chapter are relevant in every phase of the API lifecycle. Core principles are the essential rules applicable to the entire API lifecycle. These are the backbone of the API-first, contract-driven API development.

API-first

Every API development MUST be treated as product development.

An API development MUST be preceded by the API design. The API design is manifested through an API description.

Every API MUST have an API description which represents the API's product requirements.

  • Every new Web API product requirement MUST be described using the OpenAPI Specification 3.0, unless there are technical constraints, OpenAPI Specification 2.0 MAY be used. YAML and JSON format are accepted.

  • Every GraphQL API product requirement MUST be described using the GraphQL Schema.

Every approved API description represents the API contract.

Similarly to the principles of any other product lifecycle, the API lifecycle begins with the appointment of a product owner. The product owner starts the API design in the context of product research that includes business and technical feasibility reasoning, business architecture and technical architectural works, followed by the actual API design, its design verification, review and contract approval, before continuing in the API lifecycle and committing to the API development and the API implementation.

It is no longer acceptable to create an API implementation first, and then, ex-post, define the API.

The aspirational product owner role may also be responsible or may align with people responsible for some or all of the following activities: business requirements & demand consolidation, representation of the API towards internal and external stakeholders, supporting potential monetization and other business implications, steering the development provider(s), tracking its implementation and ensuring the developer's experience, managing enhancements and the lifecycle of the API(s) in his/her responsibility.

This principle is also known as "API-first" (vs. previously common "API implementation first")

Approving API description

Group Standards & Guidelines does regulate the approval process of API description to become the contract. It is up to the divisions, product owners or teams to define their API description approval process. As such the approval process might differ between divisions or even teams. The approval, at minimum, should include Product Owner's consent with the API design or its change.

Single Source of Truth

The API description is the source of truth about the API (not the actual API implementation). Furthermore, every API's description MUST be stored in the Group's API description repository. The copy of the API description as stored in this repository is the master API description – the source of truth for any given API.

Contract-driven

The API description once approved becomes the contract binding everybody involved in the API lifecycle. As such approved, the API description becomes the contract which MUST be respected by all actors and utilized in tools used throughout the API lifecycle.

If a change to an API description is needed, the change MUST be approved by its Product Owner before it replaces the existing contract.

Robustness Principle

Every API and its client SHOULD be conservative in what it sends, and liberal in what it accepts (Postel's Law).

Also known as the liberal reader, the conservative sender.

A server should serve only the necessary information to satisfy a client's request.

Related to it, an API consumer must ignore any and all data that are sent by the server in addition to the data the consumer expects.

For example, if a client asks for a customer address and it receives, also, customer's orders, the client should ignore and discard the orders received.

Minimal Surface

Every API SHOULD aim for a minimal API surface without sacrificing its product requirements. The API design SHOULD NOT include unnecessary resources, relations, actions or data.

Do not design or develop features that are not immediately required.

Keeping the API surface minimal prevents problems in the future where it is challenging to remove or change already published functionality.

The API should be designed with the knowledge of a client's behavior and should not over serve the client with unwanted data or offer resources and endpoints that are not immediately needed by any of its clients.

Never Break Client

A change to an API MUST NOT break its existing clients. Any modification to an existing API MUST avoid breaking changes and MUST maintain backward compatibility.

In particular, any change to an API MUST follow the following Rules for Extending:

  • One MUST NOT take anything away
  • One MUST NOT change processing rules (semantics of actions, parameters, data and metadata)
  • One MUST NOT make optional things required
  • Anything one adds MUST be optional

To build a system where a server and its client are decoupled, both sides have to take certain precautions. The Server-side is covered by these API Standards & Guidelines. The client-side is currently out of the scope of this document, but for the sake of completeness a client should follow these rules to allow for independent API implementation development:

  • Follow the Robustness principle
  • Operate independently on API implementation's internal details
  • Not assume and rely on any upfront knowledge of the API (e.g., what resources or affordances are available)
  • Rely on HATEOAS controls to discover API functionality at the runtime, follow protocol, message and application semantics.

Do Not Expose Implementation Details

An API MUST NOT expose any information about its implementation. This includes database identifiers, internal system names, addresses and any implementation-specific content especially with the regards to message-format and application-level semantics.

API is an abstraction layer between a consumer and an API's implementation. Exposing information about the implementation leads to tight-coupling of client and server and prevents API evolution.