Best practice for partial updates in a RESTful service

Question

I am writing a RESTful service for a customer management system and I am trying to find the best practice for updating records partially  For example  I want the caller to be able to read the full record with a GET request  But for updating it only certain operations on the record are allowed  like change the status from ENABLED to DISABLED   I have more complex scenarios than this    I don t want the caller to submit the entire record with just the updated field for security reasons  it also feels like overkill    Is there a recommended way of constructing the URIs  When reading the REST books RPC style calls seem to be frowned upon   If the following call returns the full customer record for the customer with the id 123  GET  customer 123  lt customer gt       lots of attributes       lt status gt ENABLED lt  status gt       even more attributes   lt  customer gt    how should I update the status   POST  customer 123 status  lt status gt DISABLED lt  status gt   POST  customer 123 changeStatus DISABLED        Update  To augment the question  How does one incorporate  business logic calls  into a REST api  Is there an agreed way of doing this  Not all of the methods are CRUD by nature  Some are more complex  like  sendEmailToCustomer 123     mergeCustomers 123  456     countCustomers     POST  customer 123 cmd sendEmail  POST  cmd sendEmail customerId 123  GET  customer count

User · Answer

Regarding your Update   The concept of CRUD I believe has caused some confusion regarding API design  CRUD is a general low level concept for basic operations to perform on data  and HTTP verbs are just request methods  created 21 years ago  that may or may not map to a CRUD operation  In fact  try to find the presence of the CRUD acronym in the HTTP 1 0 1 1 specification   A very well explained guide that applies a pragmatic convention can be found in the Google cloud platform API documentation  It describes the concepts behind the creation of a resource based API  one that emphasizes a big amount of resources over operations  and includes the use cases that you are describing  Although is a just a convention design for their product  I think it makes a lot of sense   The base concept here  and one that produces a lot of confusion  is the mapping between  methods  and HTTP verbs  One thing is to define what  operations   methods  your API will do over which types of resources  for example  get a list of customers  or send an email   and another are the HTTP verbs  There must be a definition of both  the methods and the verbs that you plan to use and a mapping between them   It also says that  when an operation does not map exactly with a standard method  List  Get  Create  Update  Delete in this case   one may use  Custom methods   like BatchGet  which retrieves several objects based on several object id input  or SendEmail

User · Answer

Check out http   www odata org   It defines the MERGE method  so in your case it would be something like this   MERGE  customer 123   lt customer gt      lt status gt DISABLED lt  status gt   lt  customer gt    Only the status property is updated and the other values are preserved

User · Answer

It doesn t matter   In terms of REST  you can t do a GET  because it s not cacheable  but it doesn t matter if you use POST or PATCH or PUT or whatever  and it doesn t matter what the URL looks like   If you re doing REST  what matters is that when you get a representation of your resource from the server  that representation is able give the client state transition options   If your GET response had state transitions  the client just needs to know how to read them  and the server can change them if needed   Here an update is done using POST  but if it was changed to PATCH  or if the URL changes  the client still knows how to make an update        customer                operations            update                  method    POST          href    https   server customer 123              You could go as far as to list required optional parameters for the client to give back to you   It depends on the application   As far as business operations  that might be a different resource linked to from the customer resource   If you want to send an email to the customer  maybe that service is it s own resource that you can POST to  so you might include the following operation in the customer resource    email        method    POST      href    http   server emailservice send customer 1234      Some good videos  and example of the presenter s REST architecture are these   Stormpath only uses GET POST DELETE  which is fine since REST has nothing to do with what operations you use or how URLs should look  except GETs should be cacheable    https   www youtube com watch v pspy1H6A3FM  https   www youtube com watch v 5WXYw4J4QOU  http   docs stormpath com rest quickstart

User · Answer

You should use POST for partial updates   To update fields for customer 123  make a POST to  customer 123   If you want to update just the status  you could also PUT to  customer 123 status   Generally  GET requests should not have any side effects  and PUT is for writing replacing the entire resource   This follows directly from HTTP  as seen here  http   en wikipedia org wiki HTTP PUT Request methods

User · Answer

You should use PATCH for partial updates - either using json-patch documents  see http   tools ietf org html draft-ietf-appsawg-json-patch-08 or http   www mnot net blog 2012 09 05 patch  or the XML patch framework  see http   tools ietf org html rfc5261   In my opinion though  json-patch is the best fit for your kind of business data   PATCH with JSON XML patch documents has very strait forward semantics for partial updates  If you start using POST  with modified copies of the original document  for partial updates you soon run into problems where you want missing values  or  rather  null values  to represent either  ignore this property  or  set this property to the empty value  - and that leads down a rabbit hole of hacked solutions that in the end will result in your own kind of patch format   You can find a more in-depth answer here  http   soabits blogspot dk 2013 01 http-put-patch-or-post-partial-updates html

User · Answer

Use PUT for updating incomplete partial resource   You can accept jObject as parameter and parse its value to update the resource   Below is the function which you can use as a reference     public IHttpActionResult Put int id  JObject partialObject        Dictionary lt string  string gt  dictionaryObject   new Dictionary lt string  string gt          foreach  JProperty property in json Properties                  dictionaryObject Add property Name ToString    property Value ToString                int id   Convert ToInt32 dictionaryObject  id         DateTime startTime   Convert ToDateTime orderInsert  AppointmentDateTime                     Boolean isGroup   Convert ToBoolean dictionaryObject  IsGroup            Call function to update resource     update id  startTime  isGroup        return Ok appointmentModelList

User · Answer

Things to add to your augmented question  I think you can often perfectly design more complicated business actions  But you have to give away the method procedure style of thinking and think more in resources and verbs    mail sendings    POST  customers 123 mails  payload   from  x x com  subject   foo   to  y y com     The implementation of this resource   POST would then send out the mail  if necessary you could then offer something like  customer 123 outbox and then offer resource links to  customer mails  mailId    customer count  You could handle it like a search resource  including search metadata with paging and num-found info  which gives you the count of customers       GET  customers  response payload   numFound  1234  paging   self      next      previous      customer

User · Answer

You basically have two options    Use PATCH  but note that you have to define your own media type that specifies what will happen exactly  Use POST to a sub resource and return 303 See Other with the Location header pointing to the main resource  The intention of the 303 is to tell the client   I have performed your POST and the effect was that some other resource was updated  See Location header for which resource that was   POST 303 is intended for iterative additions to a resources to build up the state of some main resource and it is a perfect fit for partial updates

User · Answer

For modifying the status I think a RESTful approach is to use a logical sub-resource which describes the status of the resources  This IMO is pretty useful and clean when you have a reduced set of statuses  It makes your API more expressive without forcing the existing operations for your customer resource   Example   POST  customer active   lt -- Providing entity in the body a new customer             attributes here except status     The POST service should return the newly created customer with the id         id 123              the other fields here     The GET for the created resource would use the resource location   GET  customer 123 active   A GET  customer 123 inactive should return 404  For the PUT operation  without providing a Json entity it will just update the status  PUT  customer 123 inactive   lt -- Deactivating an existing customer   Providing an entity will allow you to update the contents of the customer and update the status at the same time   PUT  customer 123 inactive               entity fields here except id and status     You are creating a conceptual sub-resource for your customer resource  It is also consistent with Roy Fielding s 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     In this case the conceptual mapping is active-customer to customer with status ACTIVE    Read operation   GET  customer 123 active  GET  customer 123 inactive   If you make those calls one right after the other one of them must return status 404  the successful output may not include the status as it is implicit  Of course you can still use GET  customer 123 status ACTIVE INACTIVE to query the customer resource directly   The DELETE operation is interesting as the semantics can be confusing  But you have the option of not publishing that operation for this conceptual resource  or use it in accordance with your business logic   DELETE  customer 123 active   That one can take your customer to a DELETED DISABLED status or to the opposite status  ACTIVE INACTIVE

User · Answer

I am running into a similar problem  PUT on a sub-resource seems to work when you want to update only a single field  However  sometimes you want to update a bunch of things  Think of a web form representing the resource with option to change some entries  The user s submission of form should not result in a multiple PUTs    Here are two solution that I can think of    do a PUT with the entire resource  On the server-side  define the semantics that a PUT with the entire resource ignores all the values that haven t changed  do a PUT with a partial resource  On the server-side  define the semantics of this to be a merge     2 is just a bandwidth-optimization of 1  Sometimes 1 is the only option if the resource defines some fields are required fields  think proto buffers     The problem with both these approaches is how to clear a field  You will have to define a special null value  especially for proto buffers since null values are not defined for proto buffers  that will cause clearing of the field   Comments

User · Answer

RFC 7396  JSON Merge Patch  published four years after the question was posted  describes the best practices for a PATCH in terms of the format and processing rules  In a nutshell  you submit an HTTP PATCH to a target resource with the application merge-patch json MIME media type and a body representing only the parts that you want to be changed added removed and then follow the below processing rules  Rules    If the provided merge patch contains members that do not appear within the target  those members are added   If the target does contain the member  the value is replaced   Null values in the merge patch are given special meaning to indicate the removal of existing values in the target     Example test cases that illustrate the rules above  as seen in the appendix of that RFC    ORIGINAL         PATCH           RESULT --------------------------------------------   quot a quot   quot b quot           quot a quot   quot c quot           quot a quot   quot c quot      quot a quot   quot b quot           quot b quot   quot c quot           quot a quot   quot b quot                                     quot b quot   quot c quot     quot a quot   quot b quot           quot a quot  null             quot a quot   quot b quot           quot a quot  null         quot b quot   quot c quot    quot b quot   quot c quot      quot a quot    quot b quot          quot a quot   quot c quot           quot a quot   quot c quot      quot a quot   quot c quot           quot a quot    quot b quot          quot a quot    quot b quot       quot a quot               quot a quot               quot a quot        quot b quot    quot c quot          quot b quot    quot d quot          quot b quot    quot d quot                     quot c quot   null                                              quot a quot               quot a quot    1          quot a quot    1       quot b quot   quot c quot           quot a quot   quot b quot           quot c quot   quot d quot           quot c quot   quot d quot      quot a quot   quot b quot           quot c quot               quot c quot      quot a quot   quot foo quot       null            null    quot a quot   quot foo quot        quot bar quot             quot bar quot     quot e quot  null         quot a quot  1            quot e quot  null                                    quot a quot  1    1 2              quot a quot   quot b quot           quot a quot   quot b quot                     quot c quot  null                     quot a quot                quot a quot                      quot bb quot               quot bb quot                       quot ccc quot                                    null

[rest] Best practice for partial updates in a RESTful service

Examples related to rest