Is it legal to have REST resource such as /currentUser in terms of RESTful and stateless?

Question

In terms of RESTful and stateless it\'s pretty legal to have resource like

/users/123

But, the question is: is it legal to have resource that omits user id and

Answer 1

It is OK as long as you use only the data from request (HTTP Headers in your case). In other words, this may work only for users that pass authentication.

Answer 2

As @n00b says, REST isn't a formal standard - and that's probably a good thing.

The original definition comes from Roy Fielding's dissertation. - so if you're doing the things Roy recommends, your design is RESTful. There are a few other things people have added to that - for instance, the Richardson Maturity Model is pretty commonly accepted. There are a few public "standards" documents on the web, e.g. Microsoft's version. I don't think they address this question directly, though.

So, it's up to you - but for what it's worth...

I believe APIs should be consistent and predictable. If I am asking for information about a user, I don't really like that there are two ways of doing it - one by ID, and one using a magic identifier for the current user. I also don't like the idea of introducing the concept of state into the API - by saying "there's an conceptual entity in your API called current user", you are introducing the concept of statefulness, even if you use HTTP headers to manage that.

So, if your RESTful API is designed for use by client application, I think it's reasonable to ask that client to manage state, and carry around the ID for the current user. This also makes your GET requests consistently cacheable - you can theoretically cache /users/123, but you cannot cache /loggedUser.

I believe there is a logical difference with your authentication and authorization action (I've logged in, proven who I am, and therefore got access to specific resources on the system), versus "I am user 123".

The reason you might disagree with this is that it makes your API harder to discover by human beings - someone who is trying to figure out how to get information about the current user has to log in, and then remember their user ID.

Answer 3

Yes. It is very common for ReST services to make assumption about authorization context. Though making such a decision will limit usability of that route for users other than the logged on user. For example an admin might need to use that service for a specific user.

A ReST endpoint may even use Claims that exist in the Authorization context. for example return different data for a user that has logged in using certain mechanism.

of all HTTP headers, there are some that are probably not good to be used to tailor the ReST response. for example I will not use the 'referer'.

Make sure you check for any caching strategy you may have before making such design decisions.

Answer 4

It is perfectly legal as long as you keep it stateless. That is, you infer the current user from a security context provided with the HTTP request, usually a token of some kind.

For example, you perform a GET /current-user with an Authentication header containing a JWT token. The server can get most of the user info of the current user from the JWT token and complete with data from the database and retrieve it back to the caller.

I'd also recommend not to use camel case in URIs. It can be a nightmare for devs and some servers are case insensitive.

Beware, if you are holding a server user session, as you imply in your question, your API is already stateful.

Answer 5

Picking a resource locator

Using /me, /users/me, /users/myself, /users/current or similar URIs to identify a resource that corresponds to the authenticated user is perfectly fine from a REST perspective. According to Roy Thomas Fielding's dissertation, any information that can be named can be a resource:

5.2.1.1 Resources and Resource Identifiers

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time. [...]

When using the URIs mentioned above, you have an identifier for the authenticated user and it will always identify the concept of an authenticated user, regardless of which user is authenticated.

The stateless constraint

The stateless constraint is not related to how your resources are identified. The stateless constraint is about not storing any session state on server side. In this approach, each request from client to server must contain all the necessary information to be understood by the server.

See que following quote from Fielding's dissertation:

5.1.3 Stateless

[...] each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client. [...]

When targeting protected resources that require authentication, for example, every request must contain all necessary data to be properly authenticated/authorized.

---

A similar question has been answered here and here.