CODEWITHSUNDEEP
resthttp
sid_09
sid_09

Reputation: 461

HTTP REST conventions : POST, PUT or PATCH?

I have an entity in which I need to change its state to deactivate it. This process of deactivation triggers a series of actions (NOT cronjobs) on other related entities too.

I have kept the API url in this form:

https://<base_url>/version/<entity_name>/<entity_id>/deactivate

Here is my question : Should it be a POST, PUT or PATCH request ?

Arguments for each of them :

1) POST : http://restful-api-design.readthedocs.io/en/latest/methods.html#actions

2) PATCH : Because untimately we are changing some attributes of this entity and some other related entities. Hence PATCH.

3) PUT : One of my colleague says it should be PUT.

Upvotes: 0

Views: 652

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57194

The first thing to understand is that POST is fine; we've been using POST in html forms for mumble years, and it gets the job done.

PUT and PATCH are alternative methods for communicating changes to the remote system. Think remote authoring; the basic idea is that my generic editing tool sends a GET to obtain the current representation of a resource, allows me to make changes to it, and then send a new representation back.

If the returned representation is a complete copy with my edits, then my authoring tool should use PUT. If the returned representation is just the patches, then the authoring tool should use PATCH.

Note: my authoring tool is generic; as far as it can tell, it is talking to a document store. So your job, in defining your API, is to pretend to be a document store.

The actual work of deactivating the entity is a side effect of the manipulation of the integration resources in the "document store".

So if you want, the current state of the entity can be represented by a document, and if somebody sends you back a copy of the document with the entity state changed to "deactivated", then you can make that true of the entity. Similarly, if they send you a PATCH, with instructions in the body telling you to change line 7 from activated to deactivated, then you can do the same thing.

The choices are all good, provided that you conform to the semantics of POST, and PUT as described in RFC 7231 or PATCH as described in RFC 5789: PUT needs to be idempotent, PATCH needs to be atomic, and so on.

Upvotes: 1

Related Questions