API resources depending on user context

[pvdbosch]

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:

• eBox API: GET /messages retrieves the messages in the e-box of the current user
• eessi rina connector: GET /cases/{tenantCaseId}/documents/{tenantDocumentId} where the identifiers are only unique to the user, because they're created in different systems

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:

• By default, caching is already private to a single user when the Authorization header is present
• The Authorization header as key is more specific than necessary: a single user can use multiple access tokens (e.g. after token refresh)
• The "Vary: Authorization" response header is only visible at runtime; it would be more useful to have this in the API documentation

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

I propose to just recommend API designers to:

• consider the limitations of user-dependent resource URIs and identifiers when designing an API
• specify explicitly in the OpenAPI operation descriptions if a resource URI depends on user context

---

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]

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.