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.