How to design a RESTful API if the resource has relationships with other resources?

Question

Say I have 2 resources, Account and User. When someone new signs up, a POST to /account will create an account. But there is a relationship between Account and User as follows:

1. User belongs to Account
2. Account has many users
3. User is a foreign key constraint in Account (i.e. I cannot create account without a User)

As such, a POST request to /account will create an Account and a User. In such a scenario, does it violate RESTful principles since I am creating/modifying 2 resources instead of just one?

And just for discussion's sake, assume that the creating of Account and User has to happen in a transaction (i.e. if User fails to be created, then Account won't be created either).

How do I design a RESTful API that modifies resources that have relationships with other resources and has to happen in a single transaction?

Answer 1

There is no REST principle against one resource update that updates other resources, but you should inform the client of updated resources in the response.

Consider the following (I'm quoting the lines from RESTful principles by Fielding):
"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."

Imagine a resource /last_user that returns information about the last user that requested information from another resource /book_info. Now as soon as a client uses /book_info, the resource /last_user is updated and this update was not even done via the /last_user resource.

Concerning the design of a resource update that updates other resources, consider the following:

• "Any information that can be named can be a resource" including "a collection of other resources".
• "REST concentrates all of the control state into the representations received in response to interactions."
• "By default, the response to a retrieval request is cacheable and the responses to other requests are non-cacheable." "A component can override these defaults by including control data that marks the interaction as cacheable, non-cacheable or cacheable for only a limited time."

In practical terms, include the (full) details of updated resources (e.g. created account and user) in the post-response and indicate "cacheable". For more information about this practice, have a look at this answer and related question.

The single transaction requirement is a server-side implementation detail and I imagine that in most cases creation and/or update of a resource will result in a single database transaction involving the creation and/or update of several (related) database records (e.g. audit records).