SOK API Guidelines

A handbook created by developers for developers to help engineering teams align their software practices and share know-how.

Development Community

2024-11-05
v3.0.0

Abstract

APIs are the new normal when it comes to modern software architecture since they enable decoupling and easy communication between services. APIs are easy to own, deploy and operate by our teams, so we want to help our engineers with some guidelines to help them design, implement and maintain their APIs.

Our APIs enable us to build platforms that support our business needs. API First approach should be adopted in order to support those needs in a clear and structured way. API definition starts outside the code and ideally involves all actors that are relevant to the domain. 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:

are easy to understand and learn
are general and abstracted from specific implementation and use cases
are robust and easy to use
have a common look and feel
are consistent with other teams’ APIs and our global architecture

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

1 Principles

RECOMMENDED to read Zalando RESTful API and Event Guidelines as a base and use as a reference
SHOULD implement versioning
MUST have versioning strategy decided prior the first release
RECOMMENDED not use URL versioning
RECOMMENDED to use HTTP Headers to carry version information
RECOMMENDED have version information also in response headers
MUST not break backward compatibility once the version has been released

2 Appendix 1

2.1 Commentary

2.1.1 Resource

A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time. In other word, resource is unique and anything with an URL and entity is its representation of that resource in current time when requested.

Even though we’re recommending to adapt some of Zalando’s good practices, we’re not saying your APIs should be RESTful (but they can be!) or just APIs built with good old conventions with HTTP semantics on distributed World Wide Web.