Resources
A REST APIs exposes a set of resources. Resources model the data and functionality of a system. A resource can be data, processing logic, files, or anything else that a service may have access to.
Resource URI
Any resource is uniquely identified by a Uniform Resource Identifier or URI (RFC 3986).
|
URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ] example: https://api.example.org/demo/v1/demo/v1/employers/406798006?lang=nl |
URIs must be intuitively structured.
URI fragments point to a part of a resource’s representation, and are never sent to the API, but handled locally by clients. They are thereby not specified in a REST API’s specifications (OpenAPI).
Rule: URI notation [uri-notat]
Path segments and query parameters within an API SHOULD use lowerCamelCase notation to enhance readability and to separate compound names.
As lowerCamelCase is used for JSON property names as well, the casing is consistent throughout the API. Trailing slashes MUST NOT be used.
| GOOD | BAD |
|---|---|
https://api.example.org/demo/v1/socialSecretariats/331 |
https://api.example.org/demo/v1/Social_Secretariats/331 |
https://api.example.org/demo/v1/socialSecretariats/331 |
https://api.example.org/demo/v1/socialSecretariats/331/ |
https://api.example.org/demo/v1/socialSecretariats?country=BE |
https://api.example.org/demo/v1/Social_Secretariats?Country=BE |
Rule: URI extensions [uri-extens]
The URI SHOULD NOT contain a file extension.
A notable exception to this rule is the OpenAPI description (see doc resource).
Instead, look at how to express media types using HTTP headers.
GOOD: https://api.example.org/demo/v1/socialSecretariats/331
BAD: https://api.example.org/demo/v1/socialSecretariats/331.json
Rule: Query parameters [qry-filter]
The query part of a URI may be used to filter the resource output.
The query component of a URI contains a set of parameters to be interpreted as a variation or derivative of the resource. The query component can provide clients with additional interaction capabilities such as ad hoc searching and filtering.
https://api.example.org/demo/v1/socialSecretariats?q=sdworx
Filter the resource collection using a search string.
https://api.example.org/demo/v1/socialSecretariats/331?select=(name,address)
Filter the resource properties to the ones specified in the select query parameter.
https://api.example.org/demo/v1/socialSecretariats/331?lang=nl
Only return translatable properties in Dutch.
Rule: Multiple values for the same query parameter [qry-multi]
When a single query parameter can have multiple values, the parameter SHOULD be repeated for each value.
If the parameter’s name is a noun, it SHOULD be singular.
GET /cars?color=black&color=blueparameters:
- name: color
in: query
# defaults for style and explode properties are OK (style: form, explode: true)
schema:
type: array
items:
type: stringSensitive data
Rule: Sensitive data in URLs or headers [sens-dat]
Sensitive data SHOULD be put in a message payload instead of path, query or HTTP header parameters.Even though these parameters are encrypted during HTTPS transit, they are often stored in server and infrastructure logs, caches and browser history, which increases their exposure.
The Authorization and Cookie HTTP headers are an exception, as they are recognized by infrastructure as sensitive and not logged.
For operations that would otherwise be modeled as URLs containing sensitive data, the sensitive data SHOULD instead be put in the request payload of a POST operation.
A verb suffix get, update, delete or query SHOULD be used for operations that would otherwise not use the POST method.
Resource linking, caching or embedding are not possible for such URLs.
For a single type of interaction with an entity (e.g. consult, update, delete or query), avoid introducing multiple API operations.Querying usually supports more parameters, so is more often sensitive.
If sensitive data needs to be fully hidden from middleboxes, clients or servers, even in the message payload, consider alternatives like end-to-end encryption or pseudonymization.
| suffix | original URL example | safe URL example |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
none |
|
|
none |
|
|