Skip to content

Latest commit

 

History

History
96 lines (72 loc) · 4.25 KB

general-guidelines.adoc

File metadata and controls

96 lines (72 loc) · 4.25 KB
Raw

General guidelines

The titles are marked with the corresponding labels: {MUST}, {SHOULD}, {MAY}.

{MUST} follow API first principle

You must follow the API First Principle, more specifically:

  • You must define APIs first, before coding its implementation, using OpenAPI as specification language

  • You must design your APIs consistently with these guidelines; use of a linter for automated rule checks.

  • You must call for early review feedback from peers and client developers for all component external APIs, i.e. all apis with x-api-audience =/= component-internal (see API Audience).

{MUST} provide API specification using OpenAPI

We use the OpenAPI 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 encourage to use OpenAPI 3.0 version, but still support OpenAPI 2.0 (a.k.a. Swagger 2).

The API specification files should be subject to version control using a source code management system - best together with the implementing sources.

You must / should publish the component external / internal API specification with the deployment of the implementing service.

Hint: A good way to explore OpenAPI 3.0/2.0 is to navigate through the OpenAPI specification mind map and use our Swagger Plugin for IntelliJ IDEA 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 focus on resource oriented HTTP/REST API style (and related tooling and infrastructure support) for general purpose peer-to-peer microservice communication. Here, we think that GraphQL has no major benefits, but a couple of downsides compared to REST. However, GraphQL can provide a lot of value for specific target domain problems, especially backends for frontends (BFF) and mobile clients.

{SHOULD} provide API user manual

In addition to the API Specification, it is good practice to provide an API user manual to improve client developer experience, especially of engineers that are less experienced in using this API. A helpful API user manual typically describes the following API aspects:

  • API scope, purpose, and use cases

  • concrete examples of API usage

  • edge cases, error situation details, and repair hints

  • architecture context and major dependencies - including figures and sequence flows

The user manual must be published online, e.g. via our documentation hosting platform service, GH pages, or specific team web servers. Please do not forget to include a link to the API user manual into the API specification using the #/externalDocs/url property.

{MUST} write APIs using U.K. English

{MUST} only use durable and immutable remote references

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 or $ref: 'https://github.com/zalando/zally/blob/master/server/src/main/resources/api/zally-api.yaml#/schemas/LintingRequest'. 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 [151].