API Guideline

Designing high-quality, long-lasting APIs will become even more critical for us when we start to develop our business capabilities in the new product teams.

But also non-public APIs, i.e. those that are only used in one application, should meet the same high quality standards.

With this in mind, we’ve adopted "API First" as one of our key engineering principles. Microservices development begins with API definition outside the code and ideally involves ample  peer-review feedback to achieve high-quality APIs. API First encompasses a set of quality-related standards and fosters a peer review culture including a lightweight review procedure. We encourage our teams to follow them to ensure that our APIs:

Ideally, all BAHAG APIs will look like the same author created them.

The requirement level keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" used in this document (case insensitive) are to be interpreted as described in  RFC 2119.

The BAHAG Teams are responsible to fulfill these guidelines during API development and are encouraged to contribute to guideline evolution via pull requests. The documentation is written in  asciidoc, a further evolution of  markdown.

These guidelines will, to some extent, remain work in progress as our work evolves, but teams can confidently follow and trust them.

In case guidelines are changing, following rules apply:

Furthermore you should keep in mind that once an API becomes public externally available, it has to be re-reviewed and changed according to current guidelines - for sake of overall consistency.

This guideline is based on the  Zalando REST API guidelines. But every rule has been evaluated and adopted in the BAHAG context.

REST is centered around business (data) entities exposed as resources that are identified via URIs and can be manipulated via standardized CRUD-like methods using different representations, and hypermedia. RESTful APIs tend to be less use-case specific and come with less rigid client / server coupling and are more suitable for an ecosystem of (core) services providing a platform of APIs to build diverse new business services. We apply the RESTful web service principles to all kind of application (micro-) service components, independently from whether they provide functionality via the internet or intranet. Furthermore we apply the RESTful web service principles to all kind of appliation specific communication between frontend and backend.

As mentioned above, BAHAG is transforming its services and applications to a rich set of products following a Software as a Platform (SaaP) model for all internal teams and future external business partners. As a company we want to deliver products to our (internal and external) customers which can be consumed like a service.

Platform products provide their functionality via (public) APIs; hence, the design of our APIs should be based on the API as a Product principle:

Embracing 'API as a Product' facilitates a service ecosystem, which can be evolved more easily and used to experiment quickly with new business ideas by recombining core capabilities. It makes the difference between agile, innovative product service business built on a platform of APIs and ordinary enterprise integration business where APIs are provided as "appendix" of existing products to support system integration and optimised for local server-side realization.

Understand the concrete use cases of your customers and carefully check the trade-offs of your API design variants with a product mindset. Avoid short-term implementation optimizations at the expense of unnecessary client side obligations, and have a high attention on API quality and client developer experience.

In a nutshell API First requires two aspects:

By defining APIs outside the code, we want to facilitate early review feedback and also a development discipline that focus service interface design on…​

Moreover, API definitions with standardized specification format also facilitate…​

Elements of API First are also this API Guidelines and a standardized API review process as to get early review feedback from peers and client developers. Peer review is important for us to get high quality APIs, to enable architectural and design alignment and to supported development of client applications decoupled from service provider engineering life cycle.

It is important to learn, that API First is not in conflict with the agile development principles that we love. Service applications should evolve incrementally — and so its APIs. Of course, our API specification will and should evolve iteratively in different cycles; however, each starting with draft status and early team and peer review feedback. API may change and profit from implementation concerns and automated testing feedback. API evolution during development life cycle may include breaking changes for not yet productive features and as long as we have aligned the changes with the clients. Hence, API First does not mean that you must have 100% domain and requirement understanding and can never produce code before you have defined the complete API and get it confirmed by peer review.

It is crucial to request and get early feedback — as early as possible, but not before the API changes are comprehensive with focus to the next evolution step and have a certain quality (including API Guideline compliance), already confirmed via team internal reviews.

We as BAUHAUS are an international company and our APIs should be provided for all our touchpoints and in all BAUHAUS countries. That means we have

You must follow the API First Principle, more specifically:

We use the  Open API specification as standard to define API specification files. API designers are required to provide the API specification using a single self-contained YAML file to improve readability. We use the version from Open API 3.0 or above.

The API specification files should be subject to version control using a source code management system.

Hint: A good way to explore Open API 3.0 is to navigate through the  Open API specification mind map and use a plugin for your IDE to create your first API. To explore and validate/evaluate existing APIs the  Swagger Editor may be a good starting point.

Hint: We do not yet provide guidelines for  GraphQL. We currently focus on resource oriented HTTP/REST API style (and related tooling and infrastructure support) for general purpose peer-to-peer microservice communication. We will evaluate GraphQL in the future but at the moment, it will not be part of the guideline.

Normally, API specification files must be self-contained, i.e. files should not contain references to local or remote content, e.g. ../fragment.yaml#/element. The reason is, that the content referred to is in general not durable and not immutable. As a consequence, the semantic of an API may change in unexpected ways.

However, you may use remote references to resources accessible by the following service URLs.

As we control these URLs, we ensure that their content is durable and immutable. This allows to define API specifications by using fragments published via this sources, as suggested in MUST specify success and error responses [B121] COVERED BY API-LINTER LINTER SUPPORT.

Inside the API Specification, for improving client developer experience, especially of engineers that are less experienced in using this API, the specification must include the following API aspects:

Since English will be the predominant language in all development teams in the future, all specifications and documentation must be written in U.S. English. It is not necessary to translate existing documentation into U.S. English.

API specifications must contain the following Open API meta information to allow for API management (see also  info object):

Following Open API extension properties must be provided in addition:

the following extensions are mandatory and needed by team security for classifying the API

Info: For audience company-internal, external-partner and external-public, you must provide the API meta information as described above. For audience component-internal and business-unit-internal you should provide the information.

Open API allows to specify the API specification version in #/info/version. To share a common semantic of version information we expect API designers to comply to  Semantic Versioning 2.0 rules 1 to 8 and 11 restricted to the format <MAJOR>.<MINOR>.<PATCH> for versions as follows:

Additional Notes:

Example:

A marketplace Zalando has an interesting approach to classifying their APIs based upon who is consuming them. It isn’t just about APIs being published publicly, or privately, they actually have standardized their definition, and have established an OpenAPI vendor extension, so that the definition is machine readable and available via their OpenAPI.

Providing a pretty interesting way of establishing the scope and reach of each API in a way that makes each API owner think deeply about who they are/should be targeting with the service. Done in a way that makes the audience focus machine readable, and available as part of it’s OpenAPI definition which can be then used across discovery, documentation, and through API governance and security.

Based on the Zalando approach, each API must be classified with respect to the intended target audience supposed to consume the API, to facilitate differentiated standards on APIs for discoverability, changeability, quality of design and documentation, as well as permission granting. We differentiate the following API audience groups with clear organisational and legal boundaries:

Note: a smaller audience group is intentionally included in the wider group and thus does not need to be declared additionally.

The API audience is provided as API meta information in the info-block of the Open API specification and must conform to the following specification:

Note: Exactly one audience per API specification is allowed. For this reason a smaller audience group is intentionally included in the wider group and thus does not need to be declared additionally. If parts of your API have a different target audience, we recommend to split API specifications along the target audience — even if this creates redundancies.

Example:

Every API endpoint needs to be secured using OAuth 2.0. Please refer to the  Authentication section of the official Open API specification on how to specify security definitions in your API.

The following code snippet shows how to define the authorization scheme using a bearer token (e.g. JWT token).

The next code snippet applies this security scheme to all API endpoints. The bearer token of the client must have additionally the scopes scope_1 and scope_2.

APIs should define permissions to protect their resources. Thus, at least one permission should be assigned to each endpoint. Permissions are defined as shown in the MUST secure endpoints with OAuth 2.0 [B180] COVERED BY API-LINTER LINTER SUPPORT.

The naming schema for permissions corresponds to the naming schema for MUST follow naming convention for hostnames [B141] COVERED BY API-LINTER LINTER SUPPORT. Please refer to SHOULD follow naming convention for permissions (scopes) [B182] for designing permission names.

APIs should stick to component specific permissions without resource extension to avoid governance complexity of too many fine grained permissions. For the majority of use cases, restricting access to specific API endpoints using read and write is sufficient for controlling access for client types like merchant or retailer business partners, customers or operational staff. However, in some situations, where the API serves different types of resources for different owners, resource specific scopes may make sense.

Some examples for standard and resource-specific permissions:

After permission names are defined and the permission is declared in the security definition at the top of an API specification, it should be assigned to each API operation by specifying a  security requirement like this:

In very rare cases a whole API or some selected endpoints may not require specific access control. However, to make this explicit you should assign the uid pseudo permission in this case. It is the user id and always available as OAuth2 default scope.

Hint: you need not explicitly define the "Authorization" header; it is a standard header so to say implicitly defined via the security section.

Permission names in APIs must conform to the following naming pattern:

This pattern is compatible with the previous definition.

Change APIs, but keep all consumers running. Consumers usually have independent release lifecycles, focus on stability, and avoid changes that do not provide additional value. APIs are contracts between service providers and service consumers that cannot be broken via unilateral decisions.

There are two techniques to change APIs without breaking them:

We strongly encourage using compatible API extensions and discourage versioning (see SHOULD avoid versioning [B190] and [B191] below). The following guidelines for service providers (SHOULD prefer compatible extensions [B184] LINTER SUPPORT) and consumers (MUST prepare clients accept compatible API extensions [B185] ) enable us (having Postel’s Law in mind) to make compatible changes without versioning.

Note: There is a difference between incompatible and breaking changes. Incompatible changes are changes that are not covered by the compatibility rules below. Breaking changes are incompatible changes deployed into operation, and thereby breaking running API consumers. Usually, incompatible changes are breaking changes when deployed into operation. However, in specific controlled situations it is possible to deploy incompatible changes in a non-breaking way, if no API consumer is using the affected API aspects (see also Deprecation guidelines).

Hint: Please note that the compatibility guarantees are for the "on the wire" format. Binary or source compatibility of code generated from an API definition is not covered by these rules. If client implementations update their generation process to a new version of the API definition, it has to be expected that code changes are necessary.

API designers should apply the following rules to evolve RESTful APIs for services in a backward-compatible way:

Service clients should apply the robustness principle:

Service clients must be prepared for compatible API extensions of service providers:

Designers of service provider APIs should be conservative and accurate in what they accept from clients:

Not ignoring unknown input fields is a specific deviation from Postel’s Law (e.g. see also
 The Robustness Principle Reconsidered) and a strong recommendation. Servers might want to take different approach but should be aware of the following problems and be explicit in what is supported:

In specific situations, where a (known) input field is not needed anymore, it either can stay in the API definition with "not used anymore" description or can be removed from the API definition as long as the server ignores this specific parameter.

In a response body, you must always return a JSON object (and not e.g. an array) as a top level data structure to support future extensibility. JSON objects support compatible extension by additional attributes. This allows you to easily extend your response and e.g. add pagination later, without breaking backwards compatibility. See SHOULD use pagination links where applicable [B172] for an example.

Maps (see SHOULD define maps using additionalProperties [B112] ), even though technically objects, are also forbidden as top level data structures, since they don’t support compatible, future extensions.

When changing your RESTful APIs, do so in a compatible way and avoid generating additional API versions. Multiple versions can significantly complicate understanding, testing, maintaining, evolving, operating and releasing our systems ( supplementary reading).

If changing an API can’t be done in a compatible way, then proceed in one of these three ways:

With URI versioning a (major) version number is included in the path, e.g. /v1/customer-masterdata/1 or /v1/customer-masterdata/2, see also MUST use semantic versioning [B106] COVERED BY API-LINTER LINTER SUPPORT. We always point to a specific version, there is no path thats leads to the latest version.

Before shutting down an API, version of an API, or API feature the producer must make sure, that all clients have given their consent on a sunset date. Producers should help consumers to migrate to a potential new API or API feature by providing a migration manual and clearly state the time line for replacement availability and sunset (see also SHOULD add Deprecation and Sunset header to responses [B177] ). Once all clients of a sunset API feature are migrated, the producer may shut down the deprecated API feature.

If the API is consumed by any external partner, the API owner must define a reasonable time span that the API will be maintained after the producer has announced deprecation. All external partners must state consent with this after-deprecation-life-span, i.e. the minimum time span between official deprecation and first possible sunset, before they are allowed to use the API.

The API deprecation must be part of the API specification.

If an API endpoint (operation object), an input argument (parameter object), an in/out data object (schema object), or on a more fine grained level, a schema attribute or property should be deprecated, the producers must set deprecated: true for the affected element and add further explanation to the description section of the API specification. If a future shut down is planned, the producer must provide a sunset date and document in details what consumers should use instead and how to migrate.

Owners of an API, API version, or API feature used in production that is scheduled for sunset must monitor the usage of the sunset API, API version, or API feature in order to observe migration progress and avoid uncontrolled breaking effects on ongoing consumers. See also SHOULD monitor API usage [B131] .

During the deprecation phase, the producer should add a Deprecation: <date-time> (see  draft: RFC Deprecation HTTP Header) and - if also planned - a Sunset: <date-time> (see RFC 8594) header on each response affected by a deprecated element (see MUST reflect deprecation in API specifications [B175] ).

The Deprecation header can either be set to true - if a feature is retired -, or carry a deprecation time stamp, at which a replacement will become/became available and consumers must not on-board any longer (see MUST not start using deprecated APIs [B179] ). The optional Sunset time stamp carries the information when consumers latest have to stop using a feature. The sunset date should always offer an eligible time interval for switching to a replacement feature.

If multiple elements are deprecated the Deprecation and Sunset headers are expected to be set to the earliest time stamp to reflect the shortest interval consumers are expected to get active.

Note: adding the Deprecation and Sunset header is not sufficient to gain client consent to shut down an API or feature.

Hint: You must not use the Warning header to provide the deprecation info to clients. However, Warning header has a less specific semantics, will be obsolete with  draft: RFC HTTP Caching, and our syntax was not compliant with RFC 7234 — Warning header.

Clients should monitor the Deprecation and Sunset headers in HTTP responses to get information about future sunset of APIs and API features (see SHOULD add Deprecation and Sunset header to responses [B177] ). We recommend that client owners build alerts on this monitoring information to ensure alignment with service owners on required migration task.

Clients must not start using deprecated APIs, API versions, or API features.

Property names are restricted to ASCII strings. The first character must be a letter, or an underscore, and subsequent characters can be a letter, an underscore, or a number.

(It is recommended to use _ at the start of property names only for keywords like _links.)

Rationale: No established industry standard exists, but many popular Internet companies prefer snake_case: e.g. GitHub, Stack Exchange, Twitter. Others, like Google and Amazon, use both - but not only camelCase. It’s essential to establish a consistent look and feel such that JSON looks as if it came from the same hand.

Strings are a reasonable target for values that are by design enumerations.

Enum values (using enum or x-extensible-enum) need to consistently use the upper-snake case format, e.g. VALUE or YET_ANOTHER_VALUE. This approach allows to clearly distinguish values from properties or other elements.

Note: This does not apply where the actual exact values are coming from some outside source, e.g. for language codes from ISO 639-1, or when declaring possible values for a sort parameter.

A "map" here is a mapping from string keys to some other type. In JSON this is represented as an object, the key-value pairs being represented by property names and property values. In Open API schema (as well as in JSON schema) they should be represented using additionalProperties with a schema defining the value type. Such an object should normally have no other defined properties.

The map keys don’t count as property names in the sense of MUST property names must be ASCII snake_case (and never camelCase): ^[a-z_][a-z_0-9]*$ [B109] COVERED BY API-LINTER LINTER SUPPORT, and can follow whatever format is natural for their domain. Please document this in the description of the map object’s schema.

Here is an example for such a map definition (the translations property):

An actual JSON object described by this might then look like this:

To indicate they contain multiple values prefer to pluralize array names. This implies that object names should in turn be singular.

Schema based JSON properties that are by design booleans must not be presented as nulls. A boolean is essentially a closed enumeration of two values, true and false. If the content has a meaningful null value, strongly prefer to replace the boolean with enumeration of named values or statuses - for example accepted_terms_and_conditions with true or false can be replaced with terms_and_conditions with values yes, no and unknown.

Open API 3.x allows to mark properties as required and as nullable to specify whether properties may be absent ({}) or null ({"example":null}). If a property is defined to be not required and nullable (see 2nd row in Table below), this rule demands that both cases must be handled in the exact same manner by specification.

The following table shows all combinations and whether the examples are valid:

While API designers and implementers may be tempted to assign different semantics to both cases, we explicitly decide against that option, because we think that any gain in expressiveness is far outweighed by the risk of clients not understanding and implementing the subtle differences incorrectly.

Empty array values can unambiguously be represented as the empty list, [].

Dates and date-time properties should end with _at to distinguish them from boolean properties which otherwise would have very similar or even identical names:

Hint: When defining time periods with two properties like valid from and valid until whe should use these names:

Properties which specify the user together with an action should end with _by to ensure an idiomatic form.

Use the date and time formats defined by RFC 3339:

Note that the  Open API format "date-time" corresponds to "date-time" in the RFC and 2015-05-28 for a date (note that the Open API format "date" corresponds to "full-date" in the RFC). Both are specific profiles, a subset of the international standard ISO 8601.

A zone offset may be used (both, in request and responses) — this is simply defined by the standards. Dates are restricted to UTC without offsets. For example 2015-05-28T14:07:17Z. From experience we have learned that zone offsets are not easy to understand and often not correctly handled. Note also that zone offsets are different from local times that might be including daylight saving time. Localization of dates should be done by the services that provide user interfaces, if required.

When it comes to storage, all dates must be consistently stored in UTC without a zone offset. Localization must be done locally by the services that provide user interfaces, if required.

Schema based JSON properties that are by design durations and intervals could be strings formatted as recommended by ISO 8601( Appendix A of RFC 3339 contains a grammar for durations).

Use JSON-encoded body payload for transferring structured data. The JSON payload must follow RFC 7159 using a JSON object as top-level data structure (if possible) to allow for future extension. This also applies to collection resources, where one naturally would assume an array. See also MUST always return JSON objects as top-level data structures [B187] .

Additionally, the JSON payload must comply to RFC 7493, particularly

As a consequence, a JSON payload must

Other media types may be used in following cases:

Use the standard media type name application/json or application/problem+json for MUST use problem JSON [B126] COVERED BY API-LINTER LINTER SUPPORT.

Custom media types beginning with x bring no advantage compared to the standard media type for JSON, and make automated processing more difficult. They are also discouraged by RFC 6838.

 JSON Schema and  Open API define several universally useful property formats. The following table contains some additional formats that are particularly useful in an e-commerce environment.

Please notice that the list is not exhaustive and everyone is encouraged to propose additions.

Use the following standard formats for country, language and currency codes:

Whenever an API defines a property of type number or integer, the precision must be defined by the format as follows to prevent clients from guessing the precision incorrectly, and thereby changing the value unintentionally:

The precision must be translated by clients and servers into the most specific language types. E.g. for the following definitions the most specific language types in Java will translate to BigDecimal for Money.amount and int or Integer for the OrderList.page_size:

In order to make the use / consumption of multiple APIs within an application as stable and consistent as possible every API that exposes units such as length, volumes, weight etc. must expose the unit by the international version.

In addtion to the iso code an API may include the scientific notation / sign of a unit as a separate attribute (eg. SQM ⇒ m², EUR ⇒ €)

An API may provide localized names for units in a separate attribute. This should be done in accordance with the rules stated for I18N and L10n.

Use the following common money structure:

APIs are encouraged to include a reference to the global schema for Money.

Please note that APIs have to treat Money as a closed data type, i.e. it’s not meant to be used in an inheritance hierarchy. That means the following usage is not allowed:

There exist a variety of field types that are required in multiple places. To achieve consistency across all API implementations, you must use common field names and semantics whenever applicable.

Functional naming is a powerful, yet easy way to align global resources as host, permission, and event names within an the application landscape. It helps to preserve uniqueness of names while giving readers meaningful context information about the addressed component. Besides, the most important aspect is, that it allows to keep APIs stable in the case of technical and organizational changes (BAHAG for example maintains an internal naming convention for backends and frontends).

A unique functional-name is assigned to each functional component serving an API. It is built of the domain name of the functional group the component is belonging to and a unique a short identifier for the functional component itself:

Example: Currently, you can access the component-internal API with the internal host qm-domain. If you choose to make your API company-internal (that means every team can build an application using your api), you should choose a host like product-compliance for providing your API like GET product-compliance.api.bauhaus.info/documents/{document-id}/. The name "product-compliance" here is just an example, in has to be set by the responsible product team of the resource.

Depending on the MUST provide API audience [B108] COVERED BY API-LINTER LINTER SUPPORT , you must/may follow the functional naming schema for MUST follow naming convention for hostnames [B141] COVERED BY API-LINTER LINTER SUPPORT (and also SHOULD follow naming convention for permissions (scopes) [B182] , in future) as follows:

Please see the following rules for detailed functional naming patterns: * MUST follow naming convention for hostnames [B141] COVERED BY API-LINTER LINTER SUPPORT

Hostnames in APIs must, respectively should conform to the functional naming depending on the MUST provide API audience [B108] COVERED BY API-LINTER LINTER SUPPORT as follows (see MUST use functional naming schema [B140] for details and <functional-name> definition):

Example:

This applies to concrete path segments (ship-to-store) and not the names of path parameters.

Example:

This applies to path parameters like {document-id}.

Examples:

This is for consistency in your documentation (most other headers follow this convention). Avoid camelCase (without hyphens). Exceptions are common abbreviations like "ID."

Examples:

See also: HTTP Headers are case-insensitive (RFC 7230).

See Common headers and [proprietary-headers] sections for more guidance on HTTP headers.

Usually, a collection of resource instances is provided (at least the API should be ready here).

Exception: the pseudo identifier self used to specify a resource endpoint where the resource identifier is provided by authorization information (see MUST identify resources and sub-resources via path segments [B164] LINTER SUPPORT).

In most cases, all resources provided by a service are part of the public API, and therefore should be made available under the root "/" base path.

If the service should also support non-public, internal APIs — for specific operational support functions, for example — we encourage you to maintain two different API specifications and MUST provide API audience [B108] COVERED BY API-LINTER LINTER SUPPORT . For both APIs, you must not use /api as base path.

We see API’s base path as a part of deployment variant configuration. Therefore, this information has to be declared in the  server object.

You must not specify paths with duplicate or trailing slashes, e.g. /customers//addresses or /customers/. As a consequence, you must also not specify or use path variables with empty string values.

Reasoning: Non standard paths have no clear semantics. As a result, behavior for non standard paths varies between different HTTP infrastructure components and libraries. This may leads to ambiguous and unexpected results during request handling and monitoring.

We recommend to implement services robust against clients not following this rule. All services should  normalize request paths before processing by removing duplicate and trailing slashes. Hence, the following requests should refer to the same resource:

Note: path normalization is not supported by all framework out-of-the-box. Services are required to support at least the normalized path while rejecting all alternatives paths, if failing to deliver the same resource.

If you provide query support for searching, sorting, filtering, and paginating, you must stick to the following naming conventions:

REST is all about your resources, so consider the domain entities that take part in web service interaction, and aim to model your API around these using the standard HTTP methods as operation indicators. For instance, if an application has to lock articles explicitly so that only one user may edit them, create an article lock with PUT or POST instead of using a lock action.

Request:

The added benefit is that you already have a service for browsing and filtering article locks.

An API should contain the complete business processes containing all resources representing the process. This enables clients to understand the business process, foster a consistent design of the business process, allow for synergies from description and implementation perspective, and eliminates implicit invisible dependencies between APIs.

In addition, it prevents services from being designed as thin wrappers around databases, which normally tends to shift business logic to the clients.

As a rule of thumb resources should be defined to cover 90% of all its client’s use cases. A useful resource should contain as much information as necessary, but as little as possible. A great way to support the last 10% is to allow clients to specify their needs for more/less information by supporting filtering and SHOULD reduce bandwidth needs and improve responsiveness [B193] .

The API describes resources, so the only place where actions should appear is in the HTTP methods. In URLs, use only nouns. Instead of thinking of actions (verbs), it’s often helpful to think about putting a message in a letter box: e.g., instead of having the verb cancel in the url, think of sending a message to cancel an order to the cancellations letter box on the server side.

API resources represent elements of the application’s domain model. Using domain-specific nomenclature for resource names helps developers to understand the functionality and basic semantics of your resources. It also reduces the need for further documentation outside the API definition. For example, "sales-order-items" is superior to "order-items" in that it clearly indicates which business object it represents. Along these lines, "items" is too general.

To simplify encoding of resource IDs in URLs, their representation must only consist of ASCII strings using letters, numbers, underscore, minus, colon, period, and - on rare occasions - slash.

Note: slashes are only allowed to build and signal resource identifiers consisting of MAY expose compound keys as resource identifiers [B165] .

Note: to prevent ambiguities of MUST use normalized paths without empty path segments and trailing slashes [B148] COVERED BY API-LINTER LINTER SUPPORT resource identifiers must never be empty. Consequently, support of empty strings for path parameters is forbidden.

Some API resources may contain or reference sub-resources. Embedded sub-resources, which are not top-level resources, are parts of a higher-level resource and cannot be used outside of its scope. Sub-resources should be referenced by their name and identifier in the path segments as follows:

In order to improve the consumer experience, you should aim for intuitively understandable URLs, where each sub-path is a valid reference to a resource or a set of resources. For instance, if /partners/{partner-id}/addresses/{address-id} is valid, then, in principle, also /partners/{partner-id}/addresses, /partners/{partner-id} and /partners must be valid. Examples of concrete url paths:

Note: resource identifiers may be build of multiple other resource identifiers (see MAY expose compound keys as resource identifiers [B165] ).

Exception: In some situations the resource identifier is not passed as a path segment but via the authorization information, e.g. an authorization token or session cookie. Here, it is reasonable to use self as pseudo-identifier path segment. For instance, you may define /employees/self or /employees/self/personal-details as resource paths —  and may additionally define endpoints that support identifier passing in the resource path, like define /employees/{employee-id} or /employees/{employee-id}/personal-details.

If a resource is best identified by a compound key consisting of multiple other resource identifiers, it is allowed to reuse the compound key in its natural form without containing slashes instead of technical resource identifier in the resource path without violating the above rule MUST identify resources and sub-resources via path segments [B164] LINTER SUPPORT as follows:

Example paths:

Warning: Exposing a compound key as described above limits ability to evolve the structure of the resource identifier as it is no longer opaque.

To compensate for this drawback, APIs must apply a compound key abstraction consistently in all requests and responses parameters and attributes allowing consumers to treat these as technical resource identifier replacement. The use of independent compound key components must be limited to search and creation requests, as follows:

Where id-1 is representing the opaque provision of the compound key sku-1:sid-1 as technical resource identifier.

Remark: A compound key component may itself be used as another resource identifier providing another resource endpoint, e.g /article-size-advices/{sku}.

If a sub-resource is only accessible via its parent resource and may not exist without parent resource, consider using a nested URL structure, for instance:

However, if the resource can be accessed directly via its unique id, then the API should expose it as a top-level resource. For example, customer has a collection for sales orders; however, sales orders have globally unique id and some services may choose to access the orders directly, for instance:

Generating IDs can be a scaling problem in high frequency and near real time use cases. UUIDs solve this problem, as they can be generated without collisions in a distributed, non-coordinated way and without additional server round trips.

However, they also come with some disadvantages:

UUIDs should be avoided when not needed for large scale id generation. Instead, for instance, server side support with id generation can be preferred (POST on id resource, followed by idempotent PUT on entity resource). Usage of UUIDs is especially discouraged as primary keys of master and configuration data, like brand-ids or attribute-ids which have low id volume but widespread steering functionality.

Please be aware that sequential, strictly monotonically increasing numeric identifiers may reveal critical, confidential business information, like order volume, to non-privileged clients.

In any case, we should always use string rather than number type for identifiers. This gives us more flexibility to evolve the identifier naming scheme. Accordingly, if used as identifiers, UUIDs should not be qualified using a format property.

Hint: Usually, random UUID is used - see UUID version 4 in RFC 4122. Though UUID version 1 also contains leading timestamps it is not reflected by its lexicographic sorting. This deficit is addressed by  ULID (Universally Unique Lexicographically Sortable Identifier). You may favour ULID instead of UUID, for instance, for pagination use cases ordered along creation time.

To keep maintenance and service evolution manageable, we should follow "functional segmentation" and "separation of concern" design principles and do not mix different business functionalities in same API definition. In practice this means that the number of resource types exposed via an API should be limited. In this context a resource type is defined as a set of highly related resources such as a collection, its members and any direct sub-resources.

For example, the resources below would be counted as three resource types, one for customers, one for the addresses, and one for the customers' related addresses:

Note that:

Given this definition, our experience is that well defined APIs involve no more than 4 to 8 resource types. There may be exceptions with more complex business domains that require more resources, but you should first check if you can split them into separate subdomains with distinct APIs.

Nevertheless one API should hold all necessary resources to model complete business processes helping clients to understand these flows.

There are main resources (with root url paths) and sub-resources (or nested resources with non-root urls paths). Use sub-resources if their life cycle is (loosely) coupled to the main resource, i.e. the main resource works as collection resource of the subresource entities. You should use ⇐ 3 sub-resource (nesting) levels — more levels increase API complexity and url path length. (Remember, some popular web browsers do not support URLs of more than 2000 characters.)

Be compliant with the standardized HTTP method semantics summarized as follows:

Multiple identifieres should be specified by the so called bracket syntax

In such cases the requested ressource SHOULD always return an (potentially empty) array as result.

If required the API may provide an indexed access to multiple identifier by specifying the index in the square brackets.

Request methods in RESTful services can be…​

Note: The above definitions, of intended (side) effect allows the server to provide additional state changing behavior as logging, accounting, pre- fetching, etc. However, these actual effects and state changes, must not be intended by the operation so that it can be held accountable.

Method implementations must fulfill the following basic properties according to RFC 7231:

Taken over by Zalando, still needs further review.

In many cases it is helpful or even necessary to design POST and PATCH idempotent for clients to expose conflicts and prevent resource duplicate (a.k.a. zombie resources) or lost updates, e.g. if same resources may be created or changed in parallel or multiple times. To design an idempotent API endpoint owners should consider to apply one of the following three patterns.

Note: While conditional key and secondary key are focused on handling concurrent requests, the idempotency key is focused on providing the exact same responses, which is even a stronger requirement than the idempotency defined above. It can be combined with the two other patterns.

To decide, which pattern is suitable for your use case, please consult the following table showing the major properties of each pattern:

Note: The patterns applicable to PATCH can be applied in the same way to PUT and DELETE providing the same properties.

If you mainly aim to support safe retries, we suggest to apply conditional key and secondary key pattern before the Idempotency Key pattern.

Taken over by Zalando, still needs further review.

The most important pattern to design POST idempotent for creation is to introduce a resource specific secondary key provided in the request body, to eliminate the problem of duplicate (a.k.a zombie) resources.

The secondary key is stored permanently in the resource as alternate key or combined key (if consisting of multiple properties) guarded by a uniqueness constraint enforced server-side, that is visible when reading the resource. The best and often naturally existing candidate is a unique foreign key, that points to another resource having one-on-one relationship with the newly created resource, e.g. a parent process identifier.

A good example here for a secondary key is the shopping cart ID in an order resource.

Note: When using the secondary key pattern without Idempotency-Key all subsequent retries should fail with status code 409 (conflict). We suggest to avoid 200 here unless you make sure, that the delivered resource is the original one implementing a well defined behavior. Using 204 without content would be a similar well defined option.

Taken over by Zalando, still needs further review.

Header and query parameters allow to provide a collection of values, either by providing a comma-separated list of values or by repeating the parameter multiple times with different values as follows:

As Open API does not support both schemas at once, an API specification must explicitly define the collection format to guide consumers as follows:

When choosing the collection format, take into account the tool support, the escaping of special characters and the maximal URL length.

Taken over by Zalando, still needs further review.

We prefer the use of query parameters to describe resource-specific query languages for the majority of APIs because it’s native to HTTP, easy to extend and has excellent implementation support in HTTP clients and web frameworks.

Query parameters should have the following aspects specified:

How query parameters are named and used is up to individual API designers. The following examples should serve as ideas:

We don’t advocate for or against certain names because in the end APIs should be free to choose the terminology that fits their domain the best.

Taken over by Zalando, still needs further review.

Minimalistic query languages based on query parameters are suitable for simple use cases with a small set of available filters that are combined in one way and one way only (e.g. and semantics). Simple query languages are generally preferred over complex ones.

Some APIs will have a need for sophisticated and more complex query languages. Dominant examples are APIs around search (incl. faceting) and product catalogs.

Aspects that set those APIs apart from the rest include but are not limited to:

APIs that qualify for a specific, complex query language are encouraged to use nested JSON data structures and define them using Open API directly. The provides the following benefits:

JSON-specific rules and most certainly needs to make use of the GET-with-body pattern.

Taken over by Zalando, still needs further review.

Sometimes certain collection resources or queries will not list all the possible elements they have, but only those for which the current client is authorized to access.

Implicit filtering could be done on:

In such cases, the implicit filtering must be in the API specification (in its description).

Consider caching considerations when implicitly filtering.

Example:

If an employee of the company Foo accesses one of our business-to-business service and performs a GET /business-partners, it must, for legal reasons, not display any other business partner that is not owned or contractually managed by her/his company. It should never see that we are doing business also with company Bar.

Response as seen from a consumer working at FOO:

Response as seen from a consumer working at BAR:

The API Specification should then specify something like this:

APIs should define the functional, business view and abstract from implementation aspects. Success and error responses are a vital part to define how an API is used correctly.

Therefore, you must define all success and service specific error responses in your API specification. Both are part of the interface definition and provide important information for service clients to handle standard as well as exceptional situations.

Hint: In most cases it is not useful to document all technical errors, especially if they are not under control of the service provider. Thus unless a response code conveys application-specific functional semantics or is used in a none standard way that requires additional explanation, multiple error response specifications can be combined using the following pattern (see also MUST only use durable and immutable remote references [B102] ):

API designers should also think about a troubleshooting board as part of the associated online API documentation. It provides information and handling guidance on application-specific errors and is referenced via links from the API specification. This can reduce service support tasks and contribute to service client and provider performance.

You must only use standardized HTTP status codes consistently with their intended semantics. You must not invent new HTTP status codes.

RFC standards define ~60 different HTTP status codes with specific semantics (mainly RFC7231 and RFC 6585) — and there are upcoming new ones, e.g.  draft legally-restricted-status. See overview on all error codes on  Wikipedia or via  https://httpstatuses.com/) also inculding 'unofficial codes', e.g. used by popular web servers like Nginx.

Below we list the most commonly used and best understood HTTP status codes, consistent with their semantic in the RFCs. APIs should only use these to prevent misconceptions that arise from less commonly used HTTP status codes.

Important: As long as your HTTP status code usage is well covered by the semantic defined here, you should not describe it to avoid an overload with common sense information and the risk of inconsistent definitions. Only if the HTTP status code is not in the list below or its usage requires additional information aside the well defined semantic, the API specification must provide a clear description of the HTTP status code in the response.

You must use the most specific HTTP status code when returning information about your request processing status or error situations.

Some APIs are required to provide either batch or bulk requests using POST for performance reasons, i.e. for communication and processing efficiency. In this case services may be in need to signal multiple response codes for each part of an batch or bulk request. As HTTP does not provide proper guidance for handling batch/bulk requests and responses, we herewith define the following approach:

Note: These rules apply even in the case that processing of all individual parts fail or each part is executed asynchronously!

The rules are intended to allow clients to act on batch and bulk responses in a consistent way by inspecting the individual results. We explicitly reject the option to apply 200 for a completely successful batch as proposed in Nakadi’s POST /event-types/{name}/events as short cut without inspecting the result, as we want to avoid risks and expect clients to handle partial batch failures anyway.

The bulk or batch response may look as follows:

Note: while a batch defines a collection of requests triggering independent processes, a bulk defines a collection of independent resources created or updated together in one request. With respect to response processing this distinction normally does not matter.

APIs that wish to manage the request rate of clients must use the 429 (Too Many Requests) response code, if the client exceeded the request rate (see RFC 6585). Such responses must also contain header information providing further details to the client. There are two approaches a service can take for header information:

The X-RateLimit headers are:

The reason to allow both approaches is that APIs can have different needs. Retry-After is often sufficient for general load handling and request throttling scenarios and notably, does not strictly require the concept of a calling entity such as a tenant or named account. In turn this allows resource owners to minimise the amount of state they have to carry with respect to client requests. The 'X-RateLimit' headers are suitable for scenarios where clients are associated with pre-existing account or tenancy structures. 'X-RateLimit' headers are generally returned on every request and not just on a 429, which implies the service implementing the API is carrying sufficient state to track the number of requests made within a given window for each named entity.

RFC 7807 defines a Problem JSON object and the media type application/problem+json. Operations should return it (together with a suitable status code) when any problem occurred during processing and you can give more details than the status code itself can supply, whether it be caused by the client or the server (i.e. both for 4xx or 5xx error codes).

The Open API schema definition of the Problem JSON object can be found on BitBucket. You can reference it by using:

You may define custom problem types as extensions of the Problem JSON object if your API needs to return specific, additional and detailed error information.

Problem type and instance identifiers in our APIs are not meant to be resolved. RFC 7807 encourages that custom problem types are URI references that point to human-readable documentation, but we deliberately decided against that, as all important parts of the API must be documented using MUST provide API specification using Open API [B101] COVERED BY API-LINTER LINTER SUPPORT anyway. In addition, URLs tend to be fragile and not very stable over longer periods because of organizational and documentation changes and descriptions might easily get out of sync.

In order to stay compatible with RFC 7807 we proposed to use  relative URI references usually defined by absolute-path [ '?' query ] [ '#' fragment ] as simplified identifiers in type and instance fields:

Note: The use of  absolute URIs is not forbidden but strongly discouraged. If you use absolute URIs, please reference problem-1.0.0.yaml#/Problem instead.

Stack traces contain implementation details that are not part of an API, and on which clients should never rely. Moreover, stack traces can leak sensitive information that partners and third parties are not allowed to receive and may disclose insights about vulnerabilities to attackers.

APIs should support techniques for reducing bandwidth based on client needs. This holds for APIs that (might) have high payloads and/or are used in high-traffic scenarios like the public Internet and telecommunication networks. Typical examples are APIs used by mobile web app clients with (often) less bandwidth connectivity. (BAHAG is a 'Mobile First' company, so be mindful of this point.)

Common techniques include:

Each of these items is described in greater detail below.

Compress the payload of your API’s responses with gzip, unless there’s a good reason not to — for example, you are serving so many requests that the time to compress becomes a bottleneck. This helps to transport data faster over the network (fewer bytes) and makes frontends respond faster.

Though gzip compression might be the default choice for server payload, the server should also support payload without compression and its client control via Accept-Encoding request header — see also RFC 7231 Section 5.3.4. The server should indicate used gzip compression via the Content-Encoding header.

Depending on your use case and payload size, you can significantly reduce network bandwidth need by supporting filtering of returned entity fields. Here, the client can explicitly determine the subset of fields he wants to receive via the fields query parameter. (It is analogue to  GraphQL fields and simple queries, and also applied, for instance, for  Google Cloud API’s partial responses.)

Embedding related resources (also know as Resource expansion) is a great way to reduce the number of requests. In cases where clients know upfront that they need some related resources they can instruct the server to prefetch that data eagerly. Whether this is optimized on the server, e.g. a database join, or done in a generic way, e.g. an HTTP proxy that transparently embeds resources, is up to the implementation.

See MUST stick to conventional query parameters [B149]  for naming, e.g. "embed" for steering of embedded resource expansion. Please use the  BNF grammar, as already defined above for filtering, when it comes to an embedding query syntax.

Embedding a sub-resource can possibly look like this where an order resource has its order items as sub-resource (/order/{orderId}/items):

Caching has to take many aspects into account, e.g. general cacheability of response information, our guideline to protect endpoints using SSL and MUST secure endpoints with OAuth 2.0 [B180] COVERED BY API-LINTER LINTER SUPPORT, resource update and invalidation rules, existence of multiple consumer instances. As a consequence, caching is in best case complex, e.g. with respect to consistency, in worst case inefficient.

As a consequence, client side as well as transparent web caching should be avoided, unless the service supports and requires it to protect itself, e.g. in case of a heavily used and therefore rate limited master data service, i.e. data items that rarely or not at all change after creation.

As default, API providers and consumers should always set the Cache-Control header set to Cache-Control: no-store and assume the same setting, if no Cache-Control header is provided.

Note: There is no need to document this default setting. However, please make sure that your framework is attaching this header value by default, or ensure this manually, e.g. using the best practice of Spring Security as shown below. Any setup deviating from this default must be sufficiently documented.

If your service really requires to support caching, please observe the following rules:

Hint: For proper cache support, you must return 304 without content on a failed HEAD or GET request with If-None-Match: <entity-tag> instead of 412.

Hint: For etag source see MAY consider to support ETag together with If-Match/If-None-Match header [B203] .

The default setting for Cache-Control should contain the private directive for endpoints with standard MUST secure endpoints with OAuth 2.0 [B180] COVERED BY API-LINTER LINTER SUPPORT, as well as the must-revalidate directive to ensure, that the client does not use stale cache entries. Last, the max-age directive should be set to a value between a few seconds (max-age=60) and a few hours (max-age=86400) depending on the change rate of your master data and your requirements to keep clients consistent.

The default setting for Vary is harder to determine correctly. It highly depends on the API endpoint, e.g. whether it supports compression, accepts different media types, or requires other request specific headers. To support correct caching you have to carefully choose the value. However, a good first default may be:

Anyhow, this is only relevant, if you encourage clients to install generic HTTP layer client and proxy caches.

Note: generic client and proxy caching on HTTP level is hard to configure. Therefore, we strongly recommend to attach the (possibly distributed) cache directly to the service (or gateway) layer of your application. This relieves from interpreting the Vary header and greatly simplifies interpreting the Cache-Control and etag headers. Moreover, is highly efficient with respect to caching performance and overhead, and allows to support more advanced cache update and warm up patterns.

Anyhow, please carefully read RFC 7234 before adding any client or proxy cache.

Access to lists of data items must support pagination to protect the service against overload as well as for best client side iteration and batch processing experience. This holds true for all lists that are (potentially) larger than just a few hundred entries.

There are two well known page iteration techniques:

The technical conception of pagination should also consider user experience related issues. As mentioned in this  article, jumping to a specific page is far less used than navigation via next/prev page links (See SHOULD use pagination links where applicable [B172] ). This favours cursor-based over offset-based pagination.

Note: To provide a consistent look and feel of pagination patterns, you must stick to the common query parameter names defined in MUST stick to conventional query parameters [B149] .

Cursor-based pagination is eventually better and more efficient when compared to offset-based pagination. Especially when it comes to high-data volumes and/or storage in NoSQL databases.

But every product team should decide in according to theit usecases if they want to use cursor-based or offset-based pagination. The important point is to support pagination on collection resource endpoints.

Before choosing cursor-based pagination, consider the following trade-offs:

The cursor used for pagination is an opaque pointer to a page, that must never be inspected or constructed by clients. It usually encodes (encrypts) the page position, i.e. the identifier of the first or last page element, the pagination direction, and the applied query filters - or a hash over these - to safely recreate the collection. The cursor may be defined as follows:

The page information for cursor-based pagination should consist of a cursor set, that besides next may provide support for prev, first, last, and self as follows (see also Link relation fields):

Note: The support of the cursor set may be dropped in favor of SHOULD use pagination links where applicable [B172] .

Further reading:

To simplify client design, APIs should support SHOULD use simple hypertext controls for pagination and self-references [B209] for pagination over collections whenever applicable. Beside next this may comprise the support for prev, first, last, and self as link relations (see also Link relation fields for details).

The page content is transported via items, while the query object may contain the query filters applied to the collection resource as follows:

Note: In case of complex search requests, e.g. when GET with body is required, the cursor may not be able to encode all query filters. In this case, it is best practice to encode only page position and direction in the cursor and transport the query filter in the body - in the request as well as in the response. To protect the pagination sequence, in this case it is recommended, that the cursor contains a hash over all applied query filters for pagination request validation.

Remark: You should avoid providing a total count unless there is a clear need to do so. Very often, there are significant system and performance implications when supporting full counts. Especially, if the data set grows and requests become complex queries and filters drive full scans. While this is an implementation detail relative to the API, it is important to consider the ability to support serving counts over the life of a service.

We strive for a good implementation of  REST Maturity Level 2 as it enables us to build resource-oriented APIs that make full use of HTTP verbs and status codes. You can see this expressed by many rules throughout these guidelines, e.g.:

Although this is not HATEOAS, it should not prevent you from designing proper link relationships in your APIs as stated in rules below.

We do not generally recommend to implement  REST Maturity Level 3. HATEOAS comes with additional API complexity without real value in our SOA context where client and server interact via REST APIs and provide complex business functions as part of our e-commerce SaaS platform.

Our major concerns regarding the promised advantages of HATEOAS (see also  RESTistential Crisis over Hypermedia APIs,  Why I Hate HATEOAS and others for a detailed discussion):

However, we do not forbid HATEOAS; you could use it, if you checked its limitations and still see clear value for your usage scenario that justifies its additional complexity.

Links to other resource must always use full, absolute URI.

Motivation: Exposing any form of relative URI (no matter if the relative URI uses an absolute or relative path) introduces avoidable client side complexity. It also requires clarity on the base URI, which might not be given when using features like embedding subresources. The primary advantage of non-absolute URI is reduction of the payload size, which is better achievable by following the recommendation to SHOULD use gzip compression [B194]

When embedding links to other resources into representations you must use the common hypertext control object. It contains at least one attribute:

In API that contain any hypertext controls, the attribute name href is reserved for usage within hypertext controls.

The schema for hypertext controls can be derived from this model:

The name of an attribute holding such a HttpLink object specifies the relation between the object that contains the link and the linked resource. Implementations should use names from the IANA Link Relation Registry whenever appropriate. As IANA link relation names use hyphen-case notation, while this guide enforces snake_case notation for attribute names, hyphens in IANA names have to be replaced with underscores (e.g. the IANA link relation type version-history would become the attribute version_history)

Specific link objects may extend the basic link type with additional attributes, to give additional information related to the linked resource or the relationship between the source resource and the linked one.

E.g. a service providing "Person" resources could model a person who is married with some other person with a hypertext control that contains attributes which describe the other person (id, name) but also the relationship "spouse" between the two persons (since):

Hypertext controls are allowed anywhere within a JSON model. While this specification would allow  HAL, we actually don’t recommend/enforce the usage of HAL anymore as the structural separation of meta-data and data creates more harm than value to the understandability and usability of an API.

For pagination and self-references a simplified form of the MUST use common hypertext controls [B208] should be used to reduce the specification and cognitive overhead. It consists of a simple URI value in combination with the corresponding link relations, e.g. next, prev, first, last, or self.

See MUST use common hypertext controls [B208] and SHOULD use pagination links where applicable [B172] for more information and examples.

For flexibility and precision, we prefer links to be directly embedded in the JSON payload instead of being attached using the uncommon link header syntax. As a result, the use of the Link Header defined by RFC 8288 in conjunction with JSON media types is forbidden.

Content or entity headers are headers with a Content- prefix. They describe the content of the body of the message and they can be used in both, HTTP requests and responses. Commonly used content headers include but are not limited to:

Use  this list and mention its support in your Open API definition.

Taken over by Zalando, still needs further review.

The Content-Location header is optional and can be used in successful write operations (PUT, POST, or PATCH) or read operations (GET, HEAD) to guide caching and signal a receiver the actual location of the resource transmitted in the response body. This allows clients to identify the resource and to update their local copy when receiving a response with this header.

The Content-Location header can be used to support the following use cases:

Note: When using the Content-Location header, the Content-Type header has to be set as well. For example:

Taken over by Zalando, still needs further review.

As the correct usage of Content-Location with respect to semantics and caching is difficult, we discourage the use of Content-Location. In most cases it is sufficient to direct clients to the resource location by using the Location header instead without hitting the Content-Location specific ambiguities and complexities.

More details in RFC 7231 7.1.2 Location, 3.1.4.2 Content-Location

Taken over by Zalando, still needs further review.

The Prefer header defined in RFC 7240 allows clients to request processing behaviors from servers. It pre-defines a number of preferences and is extensible, to allow others to be defined. Support for the Prefer header is entirely optional and at the discretion of API designers, but as an existing Internet Standard, is recommended over defining proprietary "X-" headers for processing directives.

The Prefer header can defined like this in an API definition:

Note: Please copy only the behaviors into your Prefer header specification that are supported by your API endpoint. If necessary, specify different Prefer headers for each supported use case.

Supporting APIs may return the Preference-Applied header also defined in RFC 7240 to indicate whether a preference has been applied.

When creating or updating resources it may be necessary to expose conflicts and to prevent the 'lost update' or 'initially created' problem. Following RFC 7232 "HTTP: Conditional Requests" this can be best accomplished by supporting the etag header together with the If-Match or If-None-Match conditional header. The contents of an ETag: <entity-tag> header is either (a) a hash of the response body, (b) a hash of the last modified field of the entity, or (c) a version number or identifier of the entity version.

To expose conflicts between concurrent update operations via PUT, POST, or PATCH, the If-Match: <entity-tag> header can be used to force the server to check whether the version of the updated entity is conforming to the requested <entity-tag>. If no matching entity is found, the operation is supposed a to respond with status code 412 - precondition failed.

Beside other use cases, If-None-Match: * can be used in a similar way to expose conflicts in resource creation. If any matching entity is found, the operation is supposed a to respond with status code 412 - precondition failed.

The etag, If-Match, and If-None-Match headers can be defined as follows in the API definition:

Please see [optimistic-locking] for a detailed discussion and options.

Taken over by Zalando, still needs further review.

When creating or updating resources it can be helpful or necessary to ensure a strong idempotent behavior comprising same responses, to prevent duplicate execution in case of retries after timeout and network outages. Generally, this can be achieved by sending a client specific unique request key – that is not part of the resource – via Idempotency-Key header.

The unique request key is stored temporarily, e.g. for 24 hours, together with the response and the request hash (optionally) of the first request in a key cache, regardless of whether it succeeded or failed. The service can now look up the unique request key in the key cache and serve the response from the key cache, instead of re-executing the request, to ensure idempotent behavior. Optionally, it can check the request hash for consistency before serving the response. If the key is not in the key store, the request is executed as usual and the response is stored in the key cache.

This allows clients to safely retry requests after timeouts, network outages, etc. while receive the same response multiple times. Note: The request retry in this context requires to send the exact same request, i.e. updates of the request that would change the result are off-limits. The request hash in the key cache can protection against this misbehavior. The service is recommended to reject such a request using status code 400.

Important: To grant a reliable idempotent execution semantic, the resource and the key cache have to be updated with hard transaction semantics – considering all potential pitfalls of failures, timeouts, and concurrent requests in a distributed systems. This makes a correct implementation exceeding the local context very hard.

The Idempotency-Key header must be defined as follows, but you are free to choose your expiration time:

Hint: The key cache is not intended as request log, and therefore should have a limited lifetime, else it could easily exceed the data resource in size.

Note: The Idempotency-Key header unlike other headers in this section is not standardized in an RFC. Our only reference are the usage in the Stripe API. However, as it fit not into our section about [proprietary-headers], and we did not want to change the header name and semantic, we decided to treat it as any other common header.

Locales as specified in RFC-3066 must be used to identify locales

All APIs must implement I18N if the user can specify the language when using the API.

All APIs should require the language as a parameter to have a clear user indication which language or locale should be used.

For options of indication see further entries [B215]

Example (product API)

If the product is listed for the country code given (de in this case) the API must always provide a error response not equal to 404 (as the product exists / is sold in DE).

There is no fallback language, there has to be a clear user indication.

Owners of APIs used in production should monitor API service to get information about its using clients. This information, for instance, is useful to identify potential review partner for API changes.

Hint: A preferred way of client detection implementation is by logging of the client-id retrieved from the OAuth token.

Owners should use the API dashboard https://dashboard.api.bauhaus/. In the dashboard you see

Addionally, you can see the long-term behaviour of your API in the API View tab In the overview tab, you see the overall traffic and test quality of all APIs in our API landscape.

Every API and endpoint must inform cloudflare how the API response should be cached by Clodflare.

First of all, we use the semantic versioning, see also https://semver.org/

That means the version of an API is described with MAJOR.MINOR.PATCH

In swaggerhub and synced to your github repo you define the version of your API. See also Create  a new version of an API

In the path of your API proxy use only the MAJOR version with the following pattern

as an example:

For sure, as long as you have only one version on production, you don’t need the major in the path (currently no API has this included)

You only need a second version of your API on production if you have breaking changes, that means in this case you would have the following scenario

The "real" version of an API you can also retrieve via the /health endpoint (see https://app.swaggerhub.com/domains/BAHAG/Problem/1.1.0#/definitions/Health).

In our case (production stage) :

You will see these versions also in the  API Dashboard

Normally, we have a preprod stage for having the same behaviour as on production. But for minimizing the maintenance effort, we agreed to use the QA stage for deploying the same versions of an API as on production. Additionally for testing purposes we have the next version of an API on the QA stage.