From c5a46f6a36980e37eab4be4903a5a589dfc0752b Mon Sep 17 00:00:00 2001 From: Diderik van Wingerden Date: Fri, 7 Nov 2025 16:02:21 +0100 Subject: [PATCH 01/10] Remove BSN as example and add note to sensitive uris --- sections/designRules.md | 59 ++++++++++++++++++++++++++++------------- 1 file changed, 41 insertions(+), 18 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 4b50037..8ad5790 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -9,6 +9,7 @@ The REST architectural style is centered around the concept of a [=resource=]. A resource is an abstraction of a conceptual entity, identified by a globally unique [=URI=]. It may correspond to anything from a physical object (e.g. a building or a person) to an abstract concept (e.g. a permit, an event or today's weather). Although a resource is not tied to any specific exchange format, its current state can be transferred to clients through one or more representations, such as JSON or XML. +

Use nouns to name resources

@@ -38,6 +39,7 @@ The REST architectural style is centered around the concept of a [=resource=]. A A resource that corresponds to a single conceptual entity is referred to as a [=singular resource=]. Resources can also be logically grouped into collections, which are themselves resources and typically support operations like paging, sorting, and filtering. While collection members are often of the same type, this is not strictly required. A collection resource contains references (URIs) to the individual singular resources it includes. +

Use plural nouns to name collection resources

@@ -65,6 +67,7 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f +

Define interfaces in Dutch unless there is an official English glossary available

@@ -82,6 +85,7 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f +

Leave off trailing slashes from URIs

@@ -192,6 +196,7 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f +

Hide irrelevant implementation details

@@ -218,6 +223,7 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f +

Only apply standard HTTP methods

@@ -315,6 +321,7 @@ Although the REST architectural style does not impose a specific protocol, REST
+

Adhere to HTTP safety and idempotency semantics for operations

@@ -401,19 +408,20 @@ One of the key constraints of the REST architectural style is stateless communic To properly understand this constraint, it is important to make a distinction between two different kinds of state: -* *Session state*: information about the interactions of an end user with a particular client application within the same user session, such as the last page being viewed, the login state or form data in a multi-step registration process. Session state must reside entirely on the client (e.g. in the user's browser). -* *Resource state*: information that is permanently stored on the server beyond the scope of a single user session, such as the user's profile, a product purchase or information about a building. Resource state is persisted on the server and must be exchanged between client and server (in both directions) using representations as part of the request or response payload. This is actually where the term *REpresentational State Transfer (REST)* originates from. +- _Session state_: information about the interactions of an end user with a particular client application within the same user session, such as the last page being viewed, the login state or form data in a multi-step registration process. Session state must reside entirely on the client (e.g. in the user's browser). +- _Resource state_: information that is permanently stored on the server beyond the scope of a single user session, such as the user's profile, a product purchase or information about a building. Resource state is persisted on the server and must be exchanged between client and server (in both directions) using representations as part of the request or response payload. This is actually where the term _REpresentational State Transfer (REST)_ originates from.

It is a misconception that there should be no state at all. The stateless communication constraint should be seen from the server's point of view and states that the server should not be aware of any session state.

Stateless communication offers many advantages, including: -* *Simplicity* is increased because the server does not have to memorize 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 -* *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). +- _Simplicity_ is increased because the server does not have to memorize 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 +- _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). +

Do not maintain session state on the server

@@ -434,6 +442,7 @@ Stateless communication offers many advantages, including: Resources are often interconnected by relationships. Relationships can be modelled in different ways depending on the cardinality, semantics and more importantly, the use cases and access patterns the REST API needs to support. +

Use nested URIs for child resources

@@ -464,6 +473,7 @@ https://api.example.org/v1/comments/456 ## Operations +

Model resource operations as a sub-resource or dedicated resource

@@ -488,6 +498,7 @@ https://api.example.org/v1/comments/456 An API is as good as the accompanying documentation. The documentation has to be easily findable, searchable and publicly accessible. Most developers will first read the documentation before they start implementing. Hiding the technical documentation in PDF documents and/or behind a login creates a barrier for both developers and search engines. +

Use OpenAPI Specification for documentation

@@ -534,6 +545,7 @@ An API is as good as the accompanying documentation. The documentation has to be
+

Publish documentation in Dutch unless there is existing documentation in English

@@ -549,6 +561,7 @@ An API is as good as the accompanying documentation. The documentation has to be
+

Publish OAS document at a standard location in JSON-format

@@ -585,6 +598,7 @@ An API is as good as the accompanying documentation. The documentation has to be Changes in APIs are inevitable. APIs should therefore always be versioned, facilitating the transition between changes. +

Include a deprecation schedule when deprecating features or versions

@@ -600,6 +614,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
+

Schedule a fixed transition period for a new major API version

@@ -615,6 +630,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
+

Include the major version number in the URI

@@ -645,6 +661,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
+

Publish a changelog for API changes between versions

@@ -660,6 +677,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
+

Adhere to the Semantic Versioning model when releasing API changes

@@ -679,6 +697,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
+

Return the full version number in a response header

@@ -716,6 +735,7 @@ In order to meet the complete security objectives, every implementer MUST also a Note: security controls for signing and encrypting of application level messages are part of separate extensions: [Signing](https://geonovum.github.io/KP-APIs/API-strategie-modules/signing-jades/) and [Encryption](https://geonovum.github.io/KP-APIs/API-strategie-modules/encryption/). +

Secure connections using TLS

@@ -736,6 +756,7 @@ Note: security controls for signing and encrypting of application level messages
+

No sensitive information in URIs

@@ -745,9 +766,10 @@ Note: security controls for signing and encrypting of application level messages
Rationale
-

Even when using TLS connections, information in URIs is not secured. URIs can be cached and logged outside of the servers controlled by clients and servers. Any information contained in them should therefore be considered readable by anyone with access to the network (in the case of the internet, the whole world) and MUST NOT contain any sensitive information. This includes client secrets used for authentication, privacy sensitive information such as BSNs or any other information which should not be shared. +

Even when using TLS connections, information in URIs is not secured. URIs can be cached and logged outside of the servers controlled by clients and servers. Any information contained in them should therefore be considered readable by anyone with access to the network (in the case of the internet, the whole world) and MUST NOT contain any sensitive information. This includes client secrets used for authentication, privacy sensitive information or any other information which should not be shared.

Be aware that queries (anything after the '?' in a URI) are also part of a URI.

+

It is up to you what the definition of sensitive means for your context. The term sensitive is deliberatly not defined in this document.

@@ -866,6 +888,7 @@ For outbound filtering, the main concern is leaking of information.
+

Use CORS to control access

@@ -892,29 +915,29 @@ Clients in this class are also known as _user-agent-based_ or _single-page-appli All browser-based applications SHOULD follow the best practices specified in [OAuth 2.0 for Browser-Based Apps](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps-22). These applications can be split into three architectural patterns: -* JavaScript applications with a backend; with this class of applications, the backend is the confidential client and should intermediate any interaction, with tokens never ending up in the browser. -Effectively, these are not different from regular web-application for this security facet, even though they leverage JavaScript for implementation. -* JavaScript applications that share a domain with the API (resource server); these can leverage cookies marked as HTTP-Only, Secure and SameSite. -* JavaScript applications without a backend; these clients are considered public clients, and are potentially more vulnerable to several types of attacks, including Cross-Site Scripting (XSS), Cross Site Request Forgery (CSRF) and OAuth token theft. -In order to support these clients, the Cross-Origin Resource Sharing (CORS) policy mentioned above is critical and MUST be supported. +- JavaScript applications with a backend; with this class of applications, the backend is the confidential client and should intermediate any interaction, with tokens never ending up in the browser. + Effectively, these are not different from regular web-application for this security facet, even though they leverage JavaScript for implementation. +- JavaScript applications that share a domain with the API (resource server); these can leverage cookies marked as HTTP-Only, Secure and SameSite. +- JavaScript applications without a backend; these clients are considered public clients, and are potentially more vulnerable to several types of attacks, including Cross-Site Scripting (XSS), Cross Site Request Forgery (CSRF) and OAuth token theft. + In order to support these clients, the Cross-Origin Resource Sharing (CORS) policy mentioned above is critical and MUST be supported. ### Validate content types A REST request or response body SHOULD match the intended content type in the header. Otherwise this could cause misinterpretation at the consumer/producer side and lead to code injection/execution. -* Reject requests containing unexpected or missing content type headers with HTTP response status `406 Not Acceptable` or `415 Unsupported Media Type`. -* Avoid accidentally exposing unintended content types by explicitly defining content types e.g. Jersey (Java) `@consumes("application/json"); @produces("application/json")`. -This avoids XXE-attack vectors for example. +- Reject requests containing unexpected or missing content type headers with HTTP response status `406 Not Acceptable` or `415 Unsupported Media Type`. +- Avoid accidentally exposing unintended content types by explicitly defining content types e.g. Jersey (Java) `@consumes("application/json"); @produces("application/json")`. + This avoids XXE-attack vectors for example. It is common for REST services to allow multiple response types (e.g. `application/xml` or `application/json`, and the client specifies the preferred order of response types by the Accept header in the request. -* Do NOT simply copy the `Accept` header to the `Content-type` header of the response. -* Reject the request (ideally with a `406 Not Acceptable` response) if the Accept header does not specifically contain one of the allowable types. +- Do NOT simply copy the `Accept` header to the `Content-type` header of the response. +- Reject the request (ideally with a `406 Not Acceptable` response) if the Accept header does not specifically contain one of the allowable types. Services (potentially) including script code (e.g. JavaScript) in their responses MUST be especially careful to defend against header injection attacks. -* Ensure the intended Content-Type headers are sent in the response, matching the body content, e.g. `application/json` and not `application/javascript`. +- Ensure the intended Content-Type headers are sent in the response, matching the body content, e.g. `application/json` and not `application/javascript`. ## Geospatial From 65f8b052a781f0f9c15636edcdd9f9a5e246bb76 Mon Sep 17 00:00:00 2001 From: Diderik van Wingerden Date: Fri, 21 Nov 2025 09:26:38 +0100 Subject: [PATCH 02/10] Major edit of text --- sections/designRules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 8ad5790..010295b 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -766,10 +766,10 @@ Note: security controls for signing and encrypting of application level messages
Rationale
-

Even when using TLS connections, information in URIs is not secured. URIs can be cached and logged outside of the servers controlled by clients and servers. Any information contained in them should therefore be considered readable by anyone with access to the network (in the case of the internet, the whole world) and MUST NOT contain any sensitive information. This includes client secrets used for authentication, privacy sensitive information or any other information which should not be shared. +

When using TLS connections, the path and query information in URIs are secured just like the message headers and body. However, before the TLS connection starts on the server, after the TLS connection ends on the client and whenever the TLS protocol is broken in between, URIs can be cached and logged, as can headers and bodies. For REST API's that are accessed directly from user devices, like web browsers, do not put client secrets used for authentication, privacy sensitive information or any other information which should not be shared in the URI, since these are directly visible to users, are stored in the web browser's history and cache and can be bookmarked and sent to others.

Be aware that queries (anything after the '?' in a URI) are also part of a URI.

-

It is up to you what the definition of sensitive means for your context. The term sensitive is deliberatly not defined in this document.

+

The term sensitive is deliberatly left undefined in this document.

From b9b3ff1b62a64ecd41371a25c0b0f4096fd07304 Mon Sep 17 00:00:00 2001 From: Diderik van Wingerden Date: Fri, 28 Nov 2025 15:06:04 +0100 Subject: [PATCH 03/10] Reversed styling changes --- sections/designRules.md | 34 ++++++---------------------------- 1 file changed, 6 insertions(+), 28 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 010295b..be7185b 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -9,7 +9,6 @@ The REST architectural style is centered around the concept of a [=resource=]. A resource is an abstraction of a conceptual entity, identified by a globally unique [=URI=]. It may correspond to anything from a physical object (e.g. a building or a person) to an abstract concept (e.g. a permit, an event or today's weather). Although a resource is not tied to any specific exchange format, its current state can be transferred to clients through one or more representations, such as JSON or XML. -

Use nouns to name resources

@@ -39,7 +38,6 @@ The REST architectural style is centered around the concept of a [=resource=]. A A resource that corresponds to a single conceptual entity is referred to as a [=singular resource=]. Resources can also be logically grouped into collections, which are themselves resources and typically support operations like paging, sorting, and filtering. While collection members are often of the same type, this is not strictly required. A collection resource contains references (URIs) to the individual singular resources it includes. -

Use plural nouns to name collection resources

@@ -67,7 +65,6 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f -

Define interfaces in Dutch unless there is an official English glossary available

@@ -85,7 +82,6 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f -

Leave off trailing slashes from URIs

@@ -196,7 +192,6 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f -

Hide irrelevant implementation details

@@ -223,7 +218,6 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f -

Only apply standard HTTP methods

@@ -321,7 +315,6 @@ Although the REST architectural style does not impose a specific protocol, REST
-

Adhere to HTTP safety and idempotency semantics for operations

@@ -408,20 +401,19 @@ One of the key constraints of the REST architectural style is stateless communic To properly understand this constraint, it is important to make a distinction between two different kinds of state: -- _Session state_: information about the interactions of an end user with a particular client application within the same user session, such as the last page being viewed, the login state or form data in a multi-step registration process. Session state must reside entirely on the client (e.g. in the user's browser). -- _Resource state_: information that is permanently stored on the server beyond the scope of a single user session, such as the user's profile, a product purchase or information about a building. Resource state is persisted on the server and must be exchanged between client and server (in both directions) using representations as part of the request or response payload. This is actually where the term _REpresentational State Transfer (REST)_ originates from. +* *Session state*: information about the interactions of an end user with a particular client application within the same user session, such as the last page being viewed, the login state or form data in a multi-step registration process. Session state must reside entirely on the client (e.g. in the user's browser). +* *Resource state*: information that is permanently stored on the server beyond the scope of a single user session, such as the user's profile, a product purchase or information about a building. Resource state is persisted on the server and must be exchanged between client and server (in both directions) using representations as part of the request or response payload. This is actually where the term *REpresentational State Transfer (REST)* originates from.

It is a misconception that there should be no state at all. The stateless communication constraint should be seen from the server's point of view and states that the server should not be aware of any session state.

Stateless communication offers many advantages, including: -- _Simplicity_ is increased because the server does not have to memorize 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 -- _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). +* *Simplicity* is increased because the server does not have to memorize 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 +* *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). -

Do not maintain session state on the server

@@ -442,7 +434,6 @@ Stateless communication offers many advantages, including: Resources are often interconnected by relationships. Relationships can be modelled in different ways depending on the cardinality, semantics and more importantly, the use cases and access patterns the REST API needs to support. -

Use nested URIs for child resources

@@ -473,7 +464,6 @@ https://api.example.org/v1/comments/456 ## Operations -

Model resource operations as a sub-resource or dedicated resource

@@ -498,7 +488,6 @@ https://api.example.org/v1/comments/456 An API is as good as the accompanying documentation. The documentation has to be easily findable, searchable and publicly accessible. Most developers will first read the documentation before they start implementing. Hiding the technical documentation in PDF documents and/or behind a login creates a barrier for both developers and search engines. -

Use OpenAPI Specification for documentation

@@ -545,7 +534,6 @@ An API is as good as the accompanying documentation. The documentation has to be
-

Publish documentation in Dutch unless there is existing documentation in English

@@ -561,7 +549,6 @@ An API is as good as the accompanying documentation. The documentation has to be
-

Publish OAS document at a standard location in JSON-format

@@ -598,7 +585,6 @@ An API is as good as the accompanying documentation. The documentation has to be Changes in APIs are inevitable. APIs should therefore always be versioned, facilitating the transition between changes. -

Include a deprecation schedule when deprecating features or versions

@@ -614,7 +600,6 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
-

Schedule a fixed transition period for a new major API version

@@ -630,7 +615,6 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
-

Include the major version number in the URI

@@ -661,7 +645,6 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
-

Publish a changelog for API changes between versions

@@ -677,7 +660,6 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
-

Adhere to the Semantic Versioning model when releasing API changes

@@ -697,7 +679,6 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
-

Return the full version number in a response header

@@ -735,7 +716,6 @@ In order to meet the complete security objectives, every implementer MUST also a Note: security controls for signing and encrypting of application level messages are part of separate extensions: [Signing](https://geonovum.github.io/KP-APIs/API-strategie-modules/signing-jades/) and [Encryption](https://geonovum.github.io/KP-APIs/API-strategie-modules/encryption/). -

Secure connections using TLS

@@ -756,7 +736,6 @@ Note: security controls for signing and encrypting of application level messages
-

No sensitive information in URIs

@@ -888,7 +867,6 @@ For outbound filtering, the main concern is leaking of information.
-

Use CORS to control access

From 6c90a8c49984aa66420c74ce0f60b4b95b36bdd4 Mon Sep 17 00:00:00 2001 From: Diderik van Wingerden Date: Fri, 28 Nov 2025 15:08:10 +0100 Subject: [PATCH 04/10] Reverse more styling changes --- sections/designRules.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index be7185b..ad37c31 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -904,18 +904,18 @@ These applications can be split into three architectural patterns: A REST request or response body SHOULD match the intended content type in the header. Otherwise this could cause misinterpretation at the consumer/producer side and lead to code injection/execution. -- Reject requests containing unexpected or missing content type headers with HTTP response status `406 Not Acceptable` or `415 Unsupported Media Type`. -- Avoid accidentally exposing unintended content types by explicitly defining content types e.g. Jersey (Java) `@consumes("application/json"); @produces("application/json")`. +* Reject requests containing unexpected or missing content type headers with HTTP response status `406 Not Acceptable` or `415 Unsupported Media Type`. +* Avoid accidentally exposing unintended content types by explicitly defining content types e.g. Jersey (Java) `@consumes("application/json"); @produces("application/json")`. This avoids XXE-attack vectors for example. It is common for REST services to allow multiple response types (e.g. `application/xml` or `application/json`, and the client specifies the preferred order of response types by the Accept header in the request. -- Do NOT simply copy the `Accept` header to the `Content-type` header of the response. -- Reject the request (ideally with a `406 Not Acceptable` response) if the Accept header does not specifically contain one of the allowable types. +* Do NOT simply copy the `Accept` header to the `Content-type` header of the response. +* Reject the request (ideally with a `406 Not Acceptable` response) if the Accept header does not specifically contain one of the allowable types. Services (potentially) including script code (e.g. JavaScript) in their responses MUST be especially careful to defend against header injection attacks. -- Ensure the intended Content-Type headers are sent in the response, matching the body content, e.g. `application/json` and not `application/javascript`. +* Ensure the intended Content-Type headers are sent in the response, matching the body content, e.g. `application/json` and not `application/javascript`. ## Geospatial From 854224dc67e46738bc7dc70d3d77d0120f617959 Mon Sep 17 00:00:00 2001 From: Diderik van Wingerden Date: Fri, 28 Nov 2025 17:19:41 +0100 Subject: [PATCH 05/10] Reverse more styling changes --- sections/designRules.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index ad37c31..55961ba 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -893,10 +893,10 @@ Clients in this class are also known as _user-agent-based_ or _single-page-appli All browser-based applications SHOULD follow the best practices specified in [OAuth 2.0 for Browser-Based Apps](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps-22). These applications can be split into three architectural patterns: -- JavaScript applications with a backend; with this class of applications, the backend is the confidential client and should intermediate any interaction, with tokens never ending up in the browser. - Effectively, these are not different from regular web-application for this security facet, even though they leverage JavaScript for implementation. -- JavaScript applications that share a domain with the API (resource server); these can leverage cookies marked as HTTP-Only, Secure and SameSite. -- JavaScript applications without a backend; these clients are considered public clients, and are potentially more vulnerable to several types of attacks, including Cross-Site Scripting (XSS), Cross Site Request Forgery (CSRF) and OAuth token theft. +* JavaScript applications with a backend; with this class of applications, the backend is the confidential client and should intermediate any interaction, with tokens never ending up in the browser. +* Effectively, these are not different from regular web-application for this security facet, even though they leverage JavaScript for implementation. +* JavaScript applications that share a domain with the API (resource server); these can leverage cookies marked as HTTP-Only, Secure and SameSite. +* JavaScript applications without a backend; these clients are considered public clients, and are potentially more vulnerable to several types of attacks, including Cross-Site Scripting (XSS), Cross Site Request Forgery (CSRF) and OAuth token theft. In order to support these clients, the Cross-Origin Resource Sharing (CORS) policy mentioned above is critical and MUST be supported. ### Validate content types @@ -906,7 +906,7 @@ Otherwise this could cause misinterpretation at the consumer/producer side and l * Reject requests containing unexpected or missing content type headers with HTTP response status `406 Not Acceptable` or `415 Unsupported Media Type`. * Avoid accidentally exposing unintended content types by explicitly defining content types e.g. Jersey (Java) `@consumes("application/json"); @produces("application/json")`. - This avoids XXE-attack vectors for example. +This avoids XXE-attack vectors for example. It is common for REST services to allow multiple response types (e.g. `application/xml` or `application/json`, and the client specifies the preferred order of response types by the Accept header in the request. From d945878ce41b34ec75ff782ba0cd57f7d985f75c Mon Sep 17 00:00:00 2001 From: Diderik van Wingerden Date: Fri, 28 Nov 2025 17:27:58 +0100 Subject: [PATCH 06/10] Reverse even more style changes --- sections/designRules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 55961ba..0716bf2 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -894,10 +894,10 @@ All browser-based applications SHOULD follow the best practices specified in [OA These applications can be split into three architectural patterns: * JavaScript applications with a backend; with this class of applications, the backend is the confidential client and should intermediate any interaction, with tokens never ending up in the browser. -* Effectively, these are not different from regular web-application for this security facet, even though they leverage JavaScript for implementation. +Effectively, these are not different from regular web-application for this security facet, even though they leverage JavaScript for implementation. * JavaScript applications that share a domain with the API (resource server); these can leverage cookies marked as HTTP-Only, Secure and SameSite. * JavaScript applications without a backend; these clients are considered public clients, and are potentially more vulnerable to several types of attacks, including Cross-Site Scripting (XSS), Cross Site Request Forgery (CSRF) and OAuth token theft. - In order to support these clients, the Cross-Origin Resource Sharing (CORS) policy mentioned above is critical and MUST be supported. +In order to support these clients, the Cross-Origin Resource Sharing (CORS) policy mentioned above is critical and MUST be supported. ### Validate content types From 9139959310152d4e6b04ead9aca26f76a1b53ec7 Mon Sep 17 00:00:00 2001 From: Diderik van Wingerden Date: Fri, 28 Nov 2025 17:29:23 +0100 Subject: [PATCH 07/10] Reverse removing extra space --- sections/designRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/designRules.md b/sections/designRules.md index 0716bf2..6bdf220 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -402,7 +402,7 @@ One of the key constraints of the REST architectural style is stateless communic To properly understand this constraint, it is important to make a distinction between two different kinds of state: * *Session state*: information about the interactions of an end user with a particular client application within the same user session, such as the last page being viewed, the login state or form data in a multi-step registration process. Session state must reside entirely on the client (e.g. in the user's browser). -* *Resource state*: information that is permanently stored on the server beyond the scope of a single user session, such as the user's profile, a product purchase or information about a building. Resource state is persisted on the server and must be exchanged between client and server (in both directions) using representations as part of the request or response payload. This is actually where the term *REpresentational State Transfer (REST)* originates from. +* *Resource state*: information that is permanently stored on the server beyond the scope of a single user session, such as the user's profile, a product purchase or information about a building. Resource state is persisted on the server and must be exchanged between client and server (in both directions) using representations as part of the request or response payload. This is actually where the term *REpresentational State Transfer (REST)* originates from.

It is a misconception that there should be no state at all. The stateless communication constraint should be seen from the server's point of view and states that the server should not be aware of any session state.

From 34d54288f5bb110637062d7f855f9acba58a075d Mon Sep 17 00:00:00 2001 From: Diderik van Wingerden Date: Fri, 28 Nov 2025 17:35:11 +0100 Subject: [PATCH 08/10] Clarify how TLS works when interrupted in between --- sections/designRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/designRules.md b/sections/designRules.md index 6bdf220..af16116 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -745,7 +745,7 @@ Note: security controls for signing and encrypting of application level messages
Rationale
-

When using TLS connections, the path and query information in URIs are secured just like the message headers and body. However, before the TLS connection starts on the server, after the TLS connection ends on the client and whenever the TLS protocol is broken in between, URIs can be cached and logged, as can headers and bodies. For REST API's that are accessed directly from user devices, like web browsers, do not put client secrets used for authentication, privacy sensitive information or any other information which should not be shared in the URI, since these are directly visible to users, are stored in the web browser's history and cache and can be bookmarked and sent to others. +

When using TLS connections, the path and query information in URIs are secured just like the message headers and body. However, before the TLS connection starts on the server, after the TLS connection ends on the client and whenever the TLS protocol is terminated and newly initiatied in between, URIs can be cached and logged, as can headers and bodies. For REST API's that are accessed directly from user devices, like web browsers, do not put client secrets used for authentication, privacy sensitive information or any other information which should not be shared in the URI, since these are directly visible to users, are stored in the web browser's history and cache and can be bookmarked and sent to others.

Be aware that queries (anything after the '?' in a URI) are also part of a URI.

The term sensitive is deliberatly left undefined in this document.

From 025f0851272a0a88423d6348966b45d0a8c9e13f Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Thu, 22 Jan 2026 10:44:55 +0100 Subject: [PATCH 09/10] Apply suggestions from code review Co-authored-by: Tim van der Lippe --- sections/designRules.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index af16116..301f333 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -745,10 +745,16 @@ Note: security controls for signing and encrypting of application level messages
Rationale
-

When using TLS connections, the path and query information in URIs are secured just like the message headers and body. However, before the TLS connection starts on the server, after the TLS connection ends on the client and whenever the TLS protocol is terminated and newly initiatied in between, URIs can be cached and logged, as can headers and bodies. For REST API's that are accessed directly from user devices, like web browsers, do not put client secrets used for authentication, privacy sensitive information or any other information which should not be shared in the URI, since these are directly visible to users, are stored in the web browser's history and cache and can be bookmarked and sent to others. +

When using TLS connections, the path and query information in URIs are secured just like the message headers and body. However, URIs can be cached and logged, as can headers and bodies in the following situations: +

    +
  • before the TLS connection starts on the server +
  • after the TLS connection ends on the client +
  • whenever the TLS protocol is terminated and newly initiated in between +
+

For REST API's that are accessed directly from user devices, like web browsers, do not put client secrets used for authentication, privacy sensitive information or any other information which should not be shared 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.

Be aware that queries (anything after the '?' in a URI) are also part of a URI.

-

The term sensitive is deliberatly left undefined in this document.

+

The term sensitive is deliberately left undefined in this document.

From a5ec16ab774573936de1d3afbbc97b13e151e1c9 Mon Sep 17 00:00:00 2001 From: Diderik van Wingerden Date: Wed, 28 Jan 2026 11:23:42 +0100 Subject: [PATCH 10/10] Aanpassing voor system-to-system --- sections/designRules.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sections/designRules.md b/sections/designRules.md index 301f333..fcfee1f 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -751,7 +751,8 @@ Note: security controls for signing and encrypting of application level messages
  • after the TLS connection ends on the client
  • whenever the TLS protocol is terminated and newly initiated in between -

    For REST API's that are accessed directly from user devices, like web browsers, do not put client secrets used for authentication, privacy sensitive information or any other information which should not be shared 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 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 interation on closed networks where all systems are under control of the involved client and server organisations, 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.

    Be aware that queries (anything after the '?' in a URI) are also part of a URI.

    The term sensitive is deliberately left undefined in this document.