Skip to content

Latest commit

 

History

History
113 lines (87 loc) · 5.19 KB

general-guidelines.adoc

File metadata and controls

113 lines (87 loc) · 5.19 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 our {zally-ui}[API Linter Service (internal_link)] for automated rule checks.

  • You must call for early review feedback from peers and client developers, and apply {api-review-proc}[our lightweight API review process (internal_link)] for all component external APIs, i.e. all apis with x-api-audience =/= component-internal (see [219]).

{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}[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 and focus on resource oriented HTTP/REST API style (and related tooling and infrastructure support). Following our {techradar-public}[Zalando Tech Radar (internal_link)], we think that GraphQL has no major benefits, but a couple of downsides compared to REST as API technology for general purpose peer-to-peer microservice communication. However, GraphQL can provide a lot of value for specific target domain problems, especially backends for frontends (BFF) and mobile clients, where typically many (domain object) resources from different services are queried and multiple roundtrip overhead should be avoided due to (mobile or public) network constraints. Therefore we list both technologies on ADOPT, though GraphQL only supplements REST for the BFF-specific problem domain.

{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. (For example, the second link is already outdated due to code restructuring.)

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].