Naming Conventions

Geonovum Handreiking
Versie ter vaststelling

Deze versie:
https://docs.geostandaarden.nl/api/vv-hr-API-Strategie-mod-naming-conventions-20231221
Laatst gepubliceerde versie:
https://docs.geostandaarden.nl/api/API-Strategie-mod-naming-conventions/
Laatste werkversie:
https://geonovum.github.io/KP-APIs/API-strategie-modules/naming-conventions/
Vorige versie:
https://docs.geostandaarden.nl/api/API-Strategie-ext/#naming-conventions
Redacteur:
Kennisplatform API's (Kennisplatform API's)
Auteur:
Kennisplatform API's (Kennisplatform API's)
Doe mee:
GitHub Geonovum/KP-APIs
Dien een melding in
Revisiehistorie
Pull requests

Samenvatting

Deze naming conventions module is gebaseerd op het naming conventions hoofdstuk van het NL API Strategie extensies document

Status van dit document

Dit is de definitieve conceptversie van dit document. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.

1. Inleiding van de NL API strategie

Dit onderdeel is niet normatief.

Dit Hoofdstuk geeft een inleiding op de Nederlandse API strategie. De stategie is opgebouwd uit meerdere documenten, standaarden en modulen. De NL API Strategie wordt doorontwikkeld en beheerd door het Kennisplatform API's.

1.1 Status

Op GitHub kan bekeken worden wat de actuele ontwikkelingen zijn met betrekking tot de Nederlandse API strategie.

1.2 Auteurs

Er worden slechts een beperkt aantal auteurs genoemd, echter aan deze strategie is door veel meer mensen gewerkt. Per onderdeel van de API strategie staan de degene verantwoordelijk voor de laatste versie vermeld. De genoemde auteurs zijn deelnemers aan de relevante werkgroep van het Kennisplatform API's zoals: API Strategie, Architectuur, Security, Design Rules, Authenticatie en Autorisatie, Strategie en Beleid, en Gebruikerswensen.

1.3 Leeswijzer

De API strategie bestaat uit een een inleidend document, verschillende normatieve documenten (NL GOV standaarden) en meerdere modulen die voor verschillende functionele of technische situaties kunnen worden ingezet. Een actueel overzicht van alle documenten is weergegeven in de onderstaande infographic:

Figuur 1 NL API Strategie Infographic

De verschillende onderdelen van de NL API Strategie bevat de volgende documenten:

Onderdeel Documentnaam &
Verwijzing naar de gepubliceerde versie
Status Versie
Algemeen Inleiding NL API Strategie Vastgesteld
(door Kennisplatform)
09-03-2022
Algemeen Architectuur NL API Strategie Vastgesteld
(door Kennisplatform)
09-03-2022
Algemeen Gebruikerswensen NL API Strategie Vastgesteld
(door Kennisplatform)
09-03-2022
Normatieve standaard API Design Rules (ADR) Verplicht
(pas toe leg uit)
09-07-2020
v1.0.0
Verplichte standaard Open API Specification (OAS) Verplicht
(pas toe leg uit)
25-05-2018
v3.0.0
Normatieve standaard NL GOV OAuth profiel Verplicht
(pas toe leg uit)
09-07-2020
v1.0.0
Voorgestelde standaard NL GOV OpenID Connect profile Verplicht
(pas toe leg uit)
18-02-2021
v1.0.0
Verplichte standaard Digikoppeling REST API koppelvlak specificatie Verplicht
(pas toe leg uit)
14-11-2022
v1.1.1
Aanvullende module API Geospatial Design Rules module Vastgesteld *
(door Kennisplatform)
23-05-2023
Aanvullende module API Transport Security module Stabiel *
(Werkgroep Kennisplatform)
11-07-2023
Aanvullende module API Access control module Stabiel
(Werkgroep Kennisplatform)
11-07-2023
Aanvullende module API Naming conventions module Stabiel
(Werkgroep Kennisplatform)
12-07-2023
Aanvullende module API Hypermedia module Stabiel
(Werkgroep Kennisplatform)
12-07-2023

2. Naming conventions

Although according to the URI specification [rfc3986] URI's are case sensitive, except the scheme/protocol (e.g. https://) and domain (e.g. api.example.org) parts, this section describes design rules related to URI's to ensure interoperability among implementations.

Specifically, design rules related to the path segments and query strings of URI's that are used to specify API resource locations are described.

2.1 Path segments

First, in order to avoid compatibility issues with web servers and frameworks that do not handle case sensitivity of URI's well, the use of spinal-case path segments is preferred over camelCase. Also, it is a more common implementation choice for path segments than snake_case.

/naming/path-case: Use spinal-case for path segments

In case path segments include compound words, the individual words are written in lower case and may be separated with hyphens.

For example, a resource representing a collection of organisatie codes, results in either a path segment organisatie-codes or organisatiecodes.

Also, the use of special characters used in path segments should be reduced to a minimum. Therefore, the use of diacritics and punctuation marks (other than hyphens, which are used in the spinal-case convention) must be avoided.

/naming/path-diacritics: Normalize characters with diacritics to their base characters for path segments

In case path segments include diacritics (e.g. accents), these characters are normalized to their base characters.

For example, a resource scènes results in path segment scenes.

/naming/path-symbols: Omit symbols and punctuation marks other than hyphens from path segments

Symbols and punctuation marks, other than hypens, must be omitted from path segments.

For example:
  • https://api.example.org/v1/schemas (' of schema's is omitted)
  • https://api.example.org/v1/hotel-restaurants (- is preserved)

With regards to naming, resources must use clear, descriptive names that expresses what the respective resources represent. Therefore, the use of nonstandard abbreviations and superfluous prefixes should be avoided in resource names.

/naming/api-resource: Do not explicitly indicate that a resource is an API

Use resource names as path segments (e.g. gebouwen) and do not explicitly mention that the resource is an API in the name (e.g. gebouwen_api).

/naming/file-extensions: Do not use file extensions in path segments

Preferably use content negotiation using the Accept header

/naming/abbreviations: Do not use nonstandard abbreviations as resource names

Avoid using nonstandard abbreviations for naming resources (e.g. /coords instead of /coordinates). This does not apply to standard or broadly used abbreviations (e.g. bagNummeraanduiding).

2.2 Query parameters

/naming/query-keys: Use lowerCamelCase for query parameter keys

Keys of query parameters must be written in lowerCamelCase. This naming convention aligns nicely with JSON property names and plays well with client side libraries such as JavaScript. Query parameters should not be prefixed with an underscore (e.g. _sort), but in case prefixing elements with underscores is required (e.g. for data API's where field names are dynamically defined by clients or to align with HAL conventions), an underscore prefix must only be used to denote meta-parameters such as _sort, _expand and _filter.

A. Referenties

A.1 Informatieve referenties

[rfc3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
Geonovum Handreiking - Versie ter vaststelling