@@ -410,7 +410,7 @@ Although the REST architectural style does not impose a specific protocol, REST
The HTTP specification [[RFC9110]] and the later introduced PATCH method specification [[RFC5789]] offer a set of standard methods, where every method is designed with explicit semantics. HTTP also defines other methods, e.g. HEAD, OPTIONS, TRACE, and CONNECT.
The OpenAPI Specification 3.0 Path Item Object also supports these methods, except for CONNECT.
According to RFC 9110 9.1 the GET and HEAD HTTP methods MUST be supported by the server, all other methods are optional.
- In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK, etc.
+ In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK, etcetera.
If an optional HTTP request method is sent to a server and the server does not support that HTTP method for the target resource, an HTTP status code 405 Method Not Allowed shall be returned and a list of allowed methods for the target resource shall be provided in the Allow header in the response as stated in RFC 9110 15.5.6.
How to test
@@ -503,7 +503,7 @@ Although the REST architectural style does not impose a specific protocol, REST
## Statelessness
-One of the key constraints of the REST architectural style is stateless communication between client and server. It means that every request from client to server must contain all of the information necessary to understand the request. The server cannot take advantage of any stored session context on the server as it didn’t memorize previous requests. Session state must therefore reside entirely on the client.
+One of the key constraints of the REST architectural style is stateless communication between client and server. It means that every request from client to server must contain all of the information necessary to understand the request. The server cannot take advantage of any stored session context on the server as it didn’t memorise previous requests. Session state must therefore reside entirely on the client.
To properly understand this constraint, it is important to make a distinction between two different kinds of state:
@@ -514,9 +514,9 @@ To properly understand this constraint, it is important to make a distinction be
Stateless communication offers many advantages, including:
-* *Simplicity* is increased because the server does not have to memorize or retrieve session state while processing requests
+* *Simplicity* is increased because the server does not have to memorise or retrieve session state while processing requests
* *Scalability* is improved because not having to incorporate session state across multiple requests enables higher concurrency and performance
-* *Observability* is improved since every request can be monitored or analyzed in isolation without having to incorporate session context from other requests
+* *Observability* is improved since every request can be monitored or analysed in isolation without having to incorporate session context from other requests
* *Reliability* is improved because it eases the task of recovering from partial failures since the server does not have to maintain, update or communicate session state. One failing request does not influence other requests (depending on the nature of the failure of course).
@@ -562,7 +562,7 @@ Resources are often interconnected by relationships. Relationships can be modell
The [=singular resources=] for comments, referenced from all 3 collections, could still be modelled on a higher level to avoid deep nesting of URIs (which might increase complexity or problems due to the URI length):
https://api.example.org/v1/comments/123
https://api.example.org/v1/comments/456
- Although this approach might seem counterintuitive from a technical perspective (we simply could have modelled a single /comments resource with optional filters for article and photo) and might introduce partially redundant functionality, it makes perfect sense from the perspective of the consumer, which increases developer experience.
+
Although this approach might seem counter-intuitive from a technical perspective (we simply could have modelled a single /comments resource with optional filters for article and photo) and might introduce partially redundant functionality, it makes perfect sense from the perspective of the consumer, which increases developer experience.
@@ -581,7 +581,7 @@ https://api.example.org/v1/comments/456
There are resource operations which might not seem to fit well in the CRUD interaction model. For example, approving a submission or notifying a customer. Depending on the type of the operation, there are three possible approaches:
- - Re-model the resource to incorporate extra fields supporting the particular operation. For example, an approval operation can be modelled in a boolean attribute
goedgekeurd that can be modified by issuing a PATCH request against the resource. A drawback of this approach is that the resource does not contain any metadata about the operation (when and by whom was the approval given? Was the submission rejected in an earlier stage?). Furthermore, this requires a fine-grained authorization model, since approval might require a specific role.
+ - Re-model the resource to incorporate extra fields supporting the particular operation. For example, an approval operation can be modelled in a boolean attribute
goedgekeurd that can be modified by issuing a PATCH request against the resource. A drawback of this approach is that the resource does not contain any metadata about the operation (when and by whom was the approval given? Was the submission rejected in an earlier stage?). Furthermore, this requires a fine-grained authorisation model, since approval might require a specific role.
- Treat the operation as a sub-resource. For example, model a sub-collection resource
/inzendingen/12/beoordelingen and add an approval or rejection by issuing a POST request. To be able to retrieve the review history (and to consistently adhere to the REST principles), also support the GET method for this resource. The /inzendingen/12 resource might still provide a goedgekeurd boolean attribute (same as approach 1) which gets automatically updated in the background after adding a review. This attribute SHOULD however be read-only.
- In exceptional cases, the approaches above still do not offer an appropriate solution. An example of such an operation is a global search across multiple resources. In this case, the creation of a dedicated resource, possibly nested under an existing resource, is the most obvious solution. Use the imperative mood of a verb, maybe even prefix it with a underscore to distinguish these resources from regular resources. For example:
/search or /_search. Depending on the operation characteristics, GET and/or POST method MAY be supported for such a resource.
@@ -649,7 +649,7 @@ Content-Type: application/problem+json{
Rationale
- To reduce the amount of roundtrips between client and server, all applicable schema validation errors SHOULD be returned together.
+
To reduce the amount of round trips between client and server, all applicable schema validation errors SHOULD be returned together.
This allows a client to present validation errors to a user in one go, reducing user friction with multiple retries.
It depends on a validation technique whether this is possible or not.
For example, when a client provides a date in the weekend, where only dates on weekdays are allowed, it depends on which service performs these validation checks.
@@ -677,7 +677,7 @@ An API is as good as the accompanying documentation. The documentation has to be
How to test
- Parse the resource at the provided location as an OpenAPI Description and confirm all $refs are resolvable and paths are defined.
+ Parse the resource at the provided location as an OpenAPI Description and confirm all $refs are resolvable and paths are defined.
@@ -751,8 +751,8 @@ An API is as good as the accompanying documentation. The documentation has to be
How to test
- - Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file (openapi.json) is publicly available, parsable, all $refs are resolvable and paths are defined.
- - Step 2: The openapi.yaml document MAY be available. If available it MUST contain YAML, be readable and parsable.
+ - Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file (openapi.json) is publicly available, parseable, all
$refs are resolvable and paths are defined.
+ - Step 2: The openapi.yaml document MAY be available. If available it MUST contain YAML, be readable and parseable.
- Step 3: The openapi.yaml document MUST contain the same OpenAPI Description as the openapi.json document.
- Step 4: The CORS header Access-Control-Allow-Origin MUST allow all origins.
@@ -830,7 +830,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
- Statement
-
- A changelog MUST be publised for every API version.
+ A changelog MUST be published for every API version.
- Rationale
-
@@ -849,7 +849,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
- Rationale
-
- Version numbering MUST follow the Semantic Versioning [[SemVer]] model to prevent breaking changes when releasing new API versions. Release versions are formatted using the
major.minor.patch template (examples: 1.0.2, 1.11.0). Pre-release versions MAY be denoted by appending a hyphen and a series of dot separated identifiers (examples: 1.0.2-rc.1, 2.0.0-beta.3). When releasing a new version which contains backwards-incompatible changes, a new major version MUST be released. Minor and patch releases MUST only contain backwards compatible changes (e.g. the addition of an endpoint or an optional attribute).
+ Version numbering MUST follow the Semantic Versioning [[SemVer]] model to prevent breaking changes when releasing new API versions. Release versions are formatted using the major.minor.patch template (examples: 1.0.2, 1.11.0). Pre-release versions MAY be denoted by appending a hyphen and a series of dot separated identifiers (examples: 1.0.2-rc.1, 2.0.0-beta.3). When releasing a new version which contains backwards-incompatible changes, a new major version MUST be released. Minor and patch releases MUST only contain backwards compatible changes (e.g. the addition of an endpoint or an optional attribute).
- How to test
-
@@ -910,7 +910,7 @@ Note: security controls for signing and encrypting of application level messages
- How to test
-
-
The usage of TLS is machine testable. Follow the latest NCSC guidelines on what is required to test. The serverside is what will be tested, only control over the server is assumed for testing. A testing client will be employed to test adherence of the server. Supporting any protocols, algorithms, key sizes, options or ciphers that are deemed insufficient or phased out by NCSC will lead to failure on the automated test. Both positive and negative scenarios are part of the test: testing that a subset of *Good* and *Sufficient* configurations are supported and configurations deemed *Insufficient* or marked for *Phase out*. A manual exception to the automated test results can be made when configurations designated for *Phase out* are supported; The API provider will have to provide clear documentation regarding the phase out schedule.
+
The usage of TLS is machine testable. Follow the latest NCSC guidelines on what is required to test. The server-side is what will be tested, only control over the server is assumed for testing. A testing client will be employed to test adherence of the server. Supporting any protocols, algorithms, key sizes, options or ciphers that are deemed insufficient or phased out by NCSC will lead to failure on the automated test. Both positive and negative scenarios are part of the test: testing that a subset of *Good* and *Sufficient* configurations are supported and configurations deemed *Insufficient* or marked for *Phase out*. A manual exception to the automated test results can be made when configurations designated for *Phase out* are supported; The API provider will have to provide clear documentation regarding the phase out schedule.
@@ -923,7 +923,7 @@ Note: security controls for signing and encrypting of application level messages
Sensitive information MUST NOT be part of URIs
The term sensitive is deliberately left undefined in this document.
- In case of REST-API's for system to system communication on a closed network, this rule applies only when there is logging involved in systems that are not under control of the organizations involved in the exchange
+
In case of REST-API's for system to system communication on a closed network, this rule applies only when there is logging involved in systems that are not under control of the organisations involved in the exchange
Rationale
@@ -935,7 +935,7 @@ Note: security controls for signing and encrypting of application level messages
Be aware that queries (anything after the '?' in a URI) are also part of a URI.
For REST API's that are accessed directly from user devices, like web browsers, do not put client secrets used for authentication and other sensitive information in the URI. These are directly visible to users, are stored in the web browser's history and cache and can be bookmarked and sent to others.
-
For REST API's that are only used for system-to-system integration on closed networks where all systems are under control of the organizations involved in the exchange, do not put client secrets used for authentication in the URI and be careful to put sensitive information in the URI. Intermediate network components that terminate and newly initiate TLS could log or otherwise store URIs. Consider the consequences, advantages and disadvantages of using sensitive information in the URI and be deliberate about which information is logged, for which purposes and who has access.
+
For REST API's that are only used for system-to-system integration on closed networks where all systems are under control of the organisations involved in the exchange, do not put client secrets used for authentication in the URI and be careful to put sensitive information in the URI. Intermediate network components that terminate and newly initiate TLS could log or otherwise store URIs. Consider the consequences, advantages and disadvantages of using sensitive information in the URI and be deliberate about which information is logged, for which purposes and who has access.
@@ -965,7 +965,7 @@ For browser-based applications a subsection is included with additional details
System-to-system (sometimes called machine-to-machine) may have a need for the listed specifications as well.
Note that different usage patterns may be applicable in contexts with system-to-system clients, see above under Client Authentication.
-Realizations may rely on internal usage of HTTP-Headers.
+Realisations may rely on internal usage of HTTP-Headers.
Information for processing requests and responses can be passed between components, that can have security implications.
For instance, this is common practice between a reverse proxy or TLS-offloader and an application server.
Additional HTTP headers are used in such example to pass an original IP-address or client certificate.
@@ -1022,7 +1022,7 @@ For outbound filtering, the main concern is leaking of information.