API Design Rules

Hoe worden de API’s getest met API Design Rules validator?

De API Design Rules (ADR) Validator is een tool die de kwaliteit van een API meet. Deze tool voert controles uit op basis van de 7 Design Rules die daadwerkelijk meetbaar zijn. Hoe hoger het aantal regels waaraan een API voldoet, hoe hoger de score.

De ADR-Validator maakt het mogelijk om tijdens het ontwikkelproces, zowel lokaal als in CI, een API te testen. Ook kan je verbeteringen in de tester aanbrengen door een merge request te openen. Zo kan je de ADR-Validator in je eigen omgeving afstemmen op je eigen behoefte! Test je API door hem te uploaden via het Developer Portaal, of raadpleeg de bot via deze link.

De 7 meetbare Design Rules zijn:

• API-03: Only apply standard HTTP methods

  The HTTP specification rfc7231 and the later introduced PATCH method specification rfc5789 offer a set of standard methods, where every method is designed with explicit semantics. Adhering to the HTTP specification is crucial, since HTTP clients and middleware applications rely on standardized characteristics. Therefore, resources must be retrieved or manipulated using standard HTTP methods.

• API-16: Use OpenAPI Specification for documentation

  The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. API documentation must be provided in the form of an OpenAPI definition document which conforms to the OpenAPI Specification (from v3 onwards). As a result, a variety of tools can be used to render the documentation (e.g. Swagger UI or ReDoc) or automate tasks such as testing or code generation. The OAS document should provide clear descriptions and examples.

• API-20: Include the major version number in the URI

  The URI of an API (base path) must include the major version number, prefixed by the letter v. This allows the exploration of multiple versions of an API in the browser. The minor and patch version numbers are not part of the URI and may not have any impact on existing client implementations.

• API-48: Leave off trailing slashes from URIs

  According to the URI specification rfc3986, URIs may contain a trailing slash. However, for REST APIs this is considered as a bad practice since a URI including or excluding a trailing slash might be interpreted as different resources (which is strictly speaking the correct interpretation). To avoid confusion and ambiguity, a URI must never contain a trailing slash. When requesting a resource including a trailing slash, this must result in a 404 (not found) error response and not a redirect. This enforces API consumers to use the correct URI.

• API-51: Publish OAS document at a standard location in JSON-format

  To make the OAS document easy to find and to facilitate self-discovering clients, there should be one standard location where the OAS document is available for download. Clients (such as Swagger UI or ReDoc) must be able to retrieve the document without having to authenticate. Furthermore, the CORS policy for this URI must allow external domains to read the documentation from a browser environment. The standard location for the OAS document is a URI called openapi.json or openapi.yaml within the base path of the API. This can be convenient, because OAS document updates can easily become part of the CI/CD process. At least the JSON format must be supported. When having multiple (major) versions of an API, every API should provide its own OAS document(s).

• API-56: Adhere to the Semantic Versioning model when releasing API changes

  Version numbering must follow the Semantic Versioning (SemVer) model to prevent breaking changes when releasing new API versions. Versions are formatted using the major.minor.patch template. When releasing a new version which contains backwards-incompatible changes, a new major version must be released. Minor and patch releases may only contain backwards compatible changes (e.g. the addition of an endpoint or an optional attribute).

• API-57: Return the full version number in a response header

  Since the URI only contains the major version, it's useful to provide the full version number in the response headers for every API call. This information could then be used for logging, debugging or auditing purposes. In cases where an intermediate networking component returns an error response (e.g. a reverse proxy enforcing access policies), the version number may be omitted. The version number must be returned in an HTTP response header named API-Version (case-insensitive) and should not be prefixed.