CODEWITHSUNDEEP
restapi-design
user644698
user644698

Reputation: 239

Modelling commands in REST api

I am looking for a good way to model commands that change the status of a resource in a REST api. I have scoured the internet and found various solutions, I would like to get feedback on the pros/cons of these.

Consider a resource that has an "isActive" state. The resource can be made active if its current "isActive" state is false and visa versa.

Solutions:

  1. Client PUTs|PATCHes to the resource with the new state.

    • PROS: Very simple.
    • CONS: No nice way to provide hypermedia to indicate to the client that the resource can be activated/deactivated.

  2. Client POSTs to resource/{id}/activate. (No body required.)

    • PROS: Hypermedia driven. Intuitive.
    • CONS: Not truly RESTful (as action is conveyed in the Uri).

  3. Client POSTs to resources/active or resources/inactive. (The body contains the id of the resource that should be added to the active resources collection)

    • PROS: Hypermedia driven.
    • CONS: Not as intuitive as option 2.

  4. Client POSTs or DELETEs to resources/{id}/isactive to indicate whether the resource is active or not.

    • PROS: Hypermedia driven.

Are they any other ways that you know of?

I quite like option 3, but have not seen this method anywhere online, so maybe it violates some REST principle!

Upvotes: 2

Views: 1053

Answers (1)

sp00m
sp00m

Reputation: 48827

Quoting https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful:

Treat it like a sub-resource with RESTful principles. For example, GitHub's API lets you star a gist with PUT /gists/{id}/star and unstar with DELETE /gists/{id}/star.

Applying this approach to your case:

  • Activating: PUT /resources/{id}/active
  • Deactivating: DELETE /resources/{id}/active

Upvotes: 0

Related Questions