belgif / rest-guide

REST Guidelines of Belgian government institutions
https://www.belgif.be/specification/rest/api-guide/
Apache License 2.0
25 stars 4 forks source link

API resources depending on user context #116

Open pvdbosch opened 1 year ago

pvdbosch commented 1 year ago

Determine guidelines concerning resource URIs that are only unique within the context of a single user.

The guide states:

"Any resource is uniquely identified by a Uniform Resource Identifier or URI (RFC 3986​)."

However, we sometimes see APIs where the resource URI depends on the user.

Examples:

Using "Vary: Authorization" in the response could make this explicit:

l'utilisation de https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary Vary: Authorization "The Vary HTTP response header describes the parts of the request message aside from the method and URL that influenced the content of the response it occurs in. Most often, this is used to create a cache key when content negotiation is in use."

However:

Similar discussion: https://stackoverflow.com/questions/28836657/http-caching-with-authorization

I propose to just recommend API designers to:


Extract RFC7234 caching: https://www.rfc-editor.org/rfc/rfc7234

A cache MUST NOT store a response to any request, unless:

 the Authorization header field (see [Section 4.2 of [RFC7235]](https://www.rfc-editor.org/rfc/rfc7235#section-4.2)) does
  not appear in the request, if the cache is shared, unless the
  response explicitly allows it

A shared cache is a cache that stores responses to be reused by more than one user; shared caches are usually (but not always) deployed as a part of an intermediary. A private cache, in contrast, is dedicated to a single user; often, they are deployed as a component of a user agent.

pvdbosch commented 1 year ago

Similar subject on resource identifier in http://opensource.zalando.com/restful-api-guidelines/#143 :

Exception: In some situations the resource identifier is not passed as a path segment but via the authorization information, e.g. an authorization token or session cookie. Here, it is reasonable to use self as pseudo-identifier path segment. For instance, you may define /employees/self or /employees/self/personal-details as resource paths —  and may additionally define endpoints that support identifier passing in the resource path, like define /employees/{empl-id} or /employees/{empl-id}/personal-details.