Skip to content

Latest commit

 

History

History
111 lines (85 loc) · 5.02 KB

general-guidelines.adoc

File metadata and controls

111 lines (85 loc) · 5.02 KB

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:

{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, and, hence, make it discoverable for the group via our API Portal [internal link].

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 or our API Portal may be a good starting point.

Hint: We do not yet provide guidelines for GraphQL. Following our Zalando Tech Radar [internal link], 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, and here we already make use of GraphQL as API technology for our DX Interface Framework.

{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, GHE 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.S. 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:

Hint: The formerly used remote references to the Problem API fragment (aliases https://opensource.zalando.com/problem/ and https://zalando.github.io/problem/) are deprecated, but still supported for compatibility ([176] on how to replace).

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 these sources, as suggested in [151].