Statelessness of a REST api with authenticated users

Including the description of the relationship type in the response body is not breaking the stateless constraint. The stateless constraint means that the web server can respond to the request without being dependent on any previous request (as has been mentioned by Tom, Jacob and kgb).

I'm not qualified to say whether what you're doing is a "best practice" or not, but in general Roy gave the following reasons for and against making your API stateless (see section 5.1.3 of his dissertation). Like many things in life there is a trade-off:

Problems with a Stateless System

• Requests may need to be larger. Since data is not stored on the server between requests, each request may need include the same things over and over again.

• In a stateless system, the server is dependent on the client maintaining the state correctly.

Benefits of a Stateless System

• You know what a request is trying to achieve based solely on its content.

• Reliability, since it "eases the task of recovering from partial failures". See reference 133 cited in Roys dissertation for more info.

• Improved scalability. Managing state between requests, particularly in a distributed environment can be quite complex. The first thing that comes to mind here is ASP.NET InProc session state, fine for a single server, single process instance, but it doesn't scale very well.

RESTful Resources

Also, according to Roy's definition of a resource I'd take issue with how I think you're defining your resources, with each user getting a slighty different "view" of the data. Roy defines a resource as a membership function that varies over time (see section 5.2.1.1 in the dissertation). The user list resource you've defined above varies by both time and by the Authorization header. Two different clients requesting /users at the same time would most likely end up with completely different results. This will make caching the results more difficult.

EDIT: Using the HTTP vary header would allow it to be cached.

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.