More and more governmental organizations offer REST APIs (henceforth abbreviated as APIs), in addition to existing interfaces like SOAP and WFS. These APIs aim to be developer-friendly and easy to implement. While this is a commendable aim, it does not shield a developer from a steep learning curve getting to know every new API, in particular when every individual API is designed using different patterns and conventions.
DocumentatieThe 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.
Naar documentatieThe OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allowsboth 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.
Naar documentatieThe 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.
Naar documentatieAccording 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.
Naar documentatieTo 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).
Naar documentatieVersion 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).
Naar documentatieSince 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.
Naar documentatieGoede metagegevens verbetert de kwaliteit van een API. Wij controleren of belangrijke metagegevens zijn ingevuld in het API-definitiebestand: specificatie, documentatie, contactgegevens en een Service Level Agreement (SLA). Het API-definitiebestand staat op GitLab (https://gitlab.com/commonground/don/don-content) en kan door iedereen worden bijgewerkt.
Het is belangrijk dat een API documentatie heeft met alle informatie die nodig is voor het eenvoudig en effectief gebruik van de API.
De API-specificatie beschrijft welke gegevens een API biedt en hoe deze gegevens kunnen worden opgevraagd.
Het is belangrijk om contactgegevens te verstrekken van degenen die verantwoordelijk zijn voor een API omdat gebruikers in contact moeten kunnen komen met iemand om problemen te rapporteren en vragen te stellen over de API.
Een Service Level Agreement (of serviceniveau-overeenkomst) is belangrijk omdat het opgeeft wat de uptime-garantie is of er een helpdesk is, en binnen hoeveel dagen de helpdesk reageert.
Secure connections using TLS following the latest National Cyber Security Center (NCSC) guidelines. Guidelines document: https://english.ncsc.nl/publications/publications/2021/january/19/it-security-guidelines-for-transport-layer-security-2.1 Note: this ruleset is in development and it does not test for the complicany of all the guidelines.
DocumentatieAll supported versions of TLS are 'Good' or 'Sufficient' (B1-1).
All supported algorithm selections contain a 'Good' or 'Sufficient' algorithm for certificate verification, key exchange, bulk encryption and hashing (B2-1 through B2-4).
Developer Overheid