Developer Overheid Ontwikkelen voor de overheid doen we samen

API Design Rules

De API Design Rules zijn een set aan ontwerpregels die zijn gebundeld in een standaard, met als oorsprong de API strategie van het Digitaal Stelsel Omgevingswet, kortweg DSO.

Bij het opstellen van de API Design Rules is de DSO API strategie het startpunt geweest en heeft de werkgroep ‘API strategie’ gekeken naar hoe deze toepasbaar gemaakt kunnen worden voor de hele Nederlandse publieke sector.

Logo omgevingswet

Digitaal Stelsel Omgevingswet

API-strategie

Pijl van links naar rechts
Logo logius

Kennisplatform API's

API Design Rules

De API Design Rules zijn ook opgenomen in de Nederlandse API strategie en omschrijft het belang van het gebruik van API's en standaarden door de overheid. De API Design Rules worden beheerd door het ‘kennisplatform API’.

Om het makkelijk te maken inzicht te krijgen in de kwaliteit van API's hebben wij een CLI gebouwd die checkt of de desbetreffende API aan de Design Rules voldoet. Deze applicatie hebben we ADR Validator genoemd en draait elke 24 uur om alle API's op ons platform van een score te voorzien.

De top10 van de best scorende API’s kan je hier vinden.

Heb je vragen over de API strategie of wil je meewerken aan het kennisplatform API, contacteer ons dan hier.

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.