Should I use PATCH or PUT in my REST API

Question

I want to design my rest endpoint with the appropriate method for the following scenario   There is a group  Each group has a status  The group can be activated or inactivated by the admin   Should I design my end point as   PUT  groups api v1 groups  group id  status activate   OR  PATCH  groups api v1 groups  group id   with request body like   action activate deactivate

User · Answer

Since you want to design an API using the REST architectural style you need to think about your use cases to decide which concepts are important enough to expose as resources. Should you decide to expose the status of a group as a sub-resource you could give it the following URI and implement support for both GET and PUT methods:

/groups/api/groups/{group id}/status

The downside of this approach over PATCH for modification is that you will not be able to make changes to more than one property of a group atomically and transactionally. If transactional changes are important then use PATCH.

If you do decide to expose the status as a sub-resource of a group it should be a link in the representation of the group. For example if the agent gets group 123 and accepts XML the response body could contain:

<group id="123">
  <status>Active</status>
  <link rel="/linkrels/groups/status" uri="/groups/api/groups/123/status"/>
  ...
</group>

A hyperlink is needed to fulfill the hypermedia as the engine of application state condition of the REST architectural style.

User · Answer

The R in REST stands for resource   Which isn t true  because it stands for Representational  but it s a good trick to remember the importance of Resources in REST    About PUT  groups api v1 groups  group id  status activate  you are not updating an  activate   An  activate  is not a thing  it s a verb  Verbs are never good resources  A rule of thumb  if the action  a verb  is in the URL  it probably is not RESTful   What are you doing instead  Either you are  adding    removing  or  updating  an activation on a Group  or if you prefer  manipulating a  status -resource on a Group  Personally  I d use  activations  because they are less ambiguous than the concept  status   creating a status is ambiguous  creating an activation is not    POST  groups  group id  activation Creates  or requests the creation of  an activation  PATCH  groups  group id  activation Updates some details of an existing activation  Since a group has only one activation  we know what activation-resource we are referring to  PUT  groups  group id  activation Inserts-or-replaces the old activation  Since a group has only one activation  we know what activation-resource we are referring to  DELETE  groups  group id  activation Will cancel  or remove the activation    This pattern is useful when the  activation  of a Group has side-effects  such as payments being made  mails being sent and so on  Only POST and PATCH may have such side-effects  When e g  a deletion of an activation needs to  say  notify users over mail  DELETE is not the right choice  in that case you probably want to create a deactivation resource  POST  groups  group id  deactivation    It is a good idea to follow these guidelines  because this standard contract makes it very clear for your clients  and all the proxies and layers between the client and you  know when it is safe to retry  and when not  Let s say the client is somewhere with flaky wifi  and its user clicks on  deactivate   which triggers a DELETE  If that fails  the client can simply retry  until it gets a 404  200 or anything else it can handle  But if it triggers a POST to deactivation it knows not to retry  the POST implies this  Any client now has a contract  which  when followed  will protect against sending out 42 emails  your group has been deactivated   simply because its HTTP-library kept retrying the call to the backend   Updating a single attribute  use PATCH  PATCH  groups  group id   In case you wish to update an attribute  E g  the  status  could be an attribute on Groups that can be set  An attribute such as  status  is often a good candidate to limit to a whitelist of values  Examples use some undefined JSON-scheme   PATCH  groups  group id     attributes      status    active      response  200 OK  PATCH  groups  group id     attributes      status    deleted      response  406 Not Acceptable   Replacing the resource  without side-effects use PUT   PUT  groups  group id   In case you wish to replace an entire Group  This does not necessarily mean that the server actually creates a new group and throws the old one out  e g  the ids might remain the same  But for the clients  this is what PUT can mean  the client should assume he gets an entirely new item  based on the server s response   The client should  in case of a PUT request  always send the entire resource  having all the data that is needed to create a new item  usually the same data as a POST-create would require   PUT  groups  group id     attributes      status    active      response  406 Not Acceptable  PUT  groups  group id     attributes      name        etc   status    active      response  201 Created or 200 OK  depending on whether we made a new one    A very important requirement is that PUT is idempotent  if you require side-effects when updating a Group  or changing an activation   you should use PATCH  So  when the update results in e g  sending out a mail  don t use PUT

User · Answer

I would recommend using PATCH  because your resource  group  has many properties but in this case  you are updating only the activation field partial modification   according to the RFC5789  https   tools ietf org html rfc5789      The existing    HTTP PUT method only allows a complete replacement of   a document     This proposal adds a new HTTP method  PATCH  to modify   an existing    HTTP resource    Also  in more details      The difference between the PUT and PATCH requests is reflected in the    way the server processes the enclosed entity to modify the resource   identified by the Request-URI   In a PUT request  the enclosed entity    is considered to be a modified version of the resource stored on the   origin server  and the client is requesting that the stored version   be replaced   With PATCH  however  the enclosed entity contains a set    of instructions describing how a resource currently residing on the   origin server should be modified to produce a new version   The PATCH    method affects the resource identified by the Request-URI  and it   also MAY have side effects on other resources  i e   new resources   may be created  or existing ones modified  by the application of a   PATCH       PATCH is neither safe nor idempotent as defined by  RFC2616     Section      9 1       Clients need to choose when to use PATCH rather than PUT   For   example  if the patch document size is larger than the size of the   new resource data that would be used in a PUT  then it might make   sense to use PUT instead of PATCH   A comparison to POST is even more    difficult  because POST is used in widely varying ways and can   encompass PUT and PATCH-like operations if the server chooses   If   the operation does not modify the resource identified by the Request-    URI in a predictable way  POST should be considered instead of PATCH   or PUT    The response code for PATCH is     The 204 response code is used because the response does not carry a      message body  which a response with the 200 code would have    Note      that other success codes could be used as well    also refer thttp   restcookbook com HTTP 20Methods patch      Caveat  An API implementing PATCH must patch atomically  It MUST not   be possible that resources are half-patched when requested by a GET

User · Answer

One possible option to implement such behavior is   PUT  groups api v1 groups  group id  status        Status   Activated      And obviously  if someone need to deactivate it  PUT will have Deactivated status in JSON   In case of necessity of mass activation deactivation  PATCH can step into the game  not for exact group  but for groups resource   PATCH  groups api v1 groups            op        replace        path         group1 status        value        Activated                op        replace        path         group7 status        value        Activated                op        replace        path         group9 status        value        Deactivated          In general this is idea as  Andrew Dobrowolski suggesting  but with slight changes in exact realization

User · Answer

The PATCH method is the correct choice here as you re updating an existing resource - the group ID   PUT should only be used if you re replacing a resource in its entirety     Further information on partial resource modification is available in RFC 5789   Specifically  the PUT method is described as follows      Several applications extending the Hypertext Transfer Protocol    HTTP     require a feature to do partial resource modification   The   existing    HTTP PUT method only allows a complete replacement of a   document     This proposal adds a new HTTP method  PATCH  to modify an   existing    HTTP resource

User · Answer

I would generally prefer something a bit simpler  like activate deactivate sub-resource  linked by a Link header with rel service    POST  groups api v1 groups  group id  activate   or  POST  groups api v1 groups  group id  deactivate   For the consumer  this interface is dead-simple  and it follows REST principles without bogging you down in conceptualizing  activations  as individual resources

[http] Should I use PATCH or PUT in my REST API?

Examples related to http

Examples related to rest

Examples related to http-put

Examples related to http-method

Examples related to http-patch