Specifically, design rules related to the path segments and query strings of URI's that are used to specify API resource locations are described.
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).
