CODEWITHSUNDEEP
rest
Adam Siemion
Adam Siemion

Reputation: 16039

REST API design of resources with many operations based on the resource status

I am designing a REST API for user management that must support the following CRUD operations:

and operations that depend on the user status:

The payload of the above requests does not contain a user representation. It contains information such as e.g. the reson why the is blocked/suspended/archived.

According to good REST design practises URIs should not API operations, so are there other ways than e.g. POST /users/{userid}/activate how such operations can be implemented?

Upvotes: 2

Views: 534

Answers (2)

cassiomolin
cassiomolin

Reputation: 130947

According to Roy T. Fielding's dissertation, any information that can be named can be a REST 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. [...]

Since the status belongs to a user, the status can be managed as a sub-resource of the user resource.

To achieve it, you could have a URL like /users/{userid}/status.

POST or PUT can be performed on this URL sending the relevant information to change the user status.

Upvotes: 3

Matthias Muth
Matthias Muth

Reputation: 71

Two possible options are for example:

  • model the action to be a part of the user resource (e.g. introduce an archived-Flag that can be set). With this approach its quirky to pass additional event-information (reason why he was archived/blocked/...), of course.
  • create a separate REST-resource, e.g. /api/archivedUsers/ where you can POST a tuple consisting of user-URI and additional event-data

both approaches have in common, that they try to model the state of your user object (REST-like), rather than performing an action on it (what feels RPC-like). You could also check this article: REST API design resource modeling.

Upvotes: 1

Related Questions