Statelessness of a REST api with authenticated users

Question

I'm currently designing a REST Http api. (With HATEOAS stuff, to make clients "simpler", and avoid clients to do complicated things, instead of letting the api tell them what to do ...)

Because of the social characteristic of the app, in order to interact with the application, users need to be authenticated, and each user will have a slighty different "view" of the data. We'll take twitter as an example, it will be easier for everyone.

To authenticate users, we'll use OAuth, easy.

So, in the client (ios app...), a random user would maybe seeing a list of users should see:

Adrien: Following John:   Not Following Rambo:  Not Following 

And another user would maybe see:

Adrien: Following John:   Not Following Rambo:  Following 

To achieve this, the first solution would be for the client (in oauth term, the iphone/web/etc app), to get a list of all the users the authenticated user follow, and each time the client displays a list, compare each user with the list of followed users to know if it should display "Not Following" or "Following".

The requests/responses would be:

GET /users Authorization: OAuth token...  [   {"id": 1, "name": "Adrien"},   {"id": 2, "name": "John"},   {"id": 3, "name": "Rambo"} ] 

and

GET /users/{myid}/following Authorization: OAuth token...  [1, 3, 25, 1210, 9] 

This seems to be quite, stateless. Good.

Now what if i want to make client developers life easier, and embed directly in the user list response, the relationship of each user, relative to the authenticated user:

GET /users Authorization: OAuth token...  [   {"id": 1, "name": "Adrien", "relationship": "Following"},   {"id": 2, "name": "John", "relationship": "Not Following"},   {"id": 3, "name": "Rambo", "relationship": "Following"} ] 

So, questions:

• It seems to break the "stateless" thing, does it really break the REST stateless constraint ?
• Next, do you think it is a good or bad practice for an api to do this ?

Answer 1

You should definitely embed the relationship in the user list response. It would be bad practice to force the clients calculate it.

This does not break the stateless constraint of REST as it's the interactions that are stateless, not the systems. The server will almost always have to store and maintain state. For instance the server will need to maintain state of who is following who.

Finally, I think you are not fully getting the "State" part of Hypermedia As The Engine Of Application State. Basically, the resources are state machines. When you GET a resource, the valid state transitions are presented has hypermedia controls (links and forms) in the response. It's by following these links and submitting the forms that the client can change the state of these resources.