Json – HTTP PATCH: Handling arrays, deletion, and nested key creation

apiArchitecturehttpjsonrest

I'm looking for a practical guide to implementing the PATCH verb for partial updates of a noun in a RESTful api using JSON. Understanding that PATCH is for partial updates, we lack still standardization around the syntax for deleting keys, creating or updating nested keys, and arrays.

Let's say I GET an object:

// GET users/42
{
  id: 42,
  name: 'SimpleAsCouldBe',
  city: 'San Francisco',
  roles: ['viewer','editor'],
  posts: {
    '01': {},
    '02': {},
  }
}

…Then I want to update it:

// PATCH users/42
{
  name: 'SimpleGuy',                   // CLEAR:   update the key's value
  email: 'hey@google.com',             // CLEAR:   add the new key
  city: null                           // UNCLEAR: delete the key?
  roles: ['owner'],                    // UNCLEAR: replace the whole array?
  posts: {
    '02': { title:'how to pop lock' }, // CLEAR:  update nested key
    '03': { title:'how to salsa' }     // CLEAR:  create new nested key
  }
  notes: {
    '01': { title: 'a note title' }    // CLEAR (but disallowed?): create wrapping key
  }
}

The PATCH rfc says no to creating nested keys. This is a spec bug, I think, because creating a nested key is non-ambiguous.

I could send a full object diff, like this library generates, but this makes the clear case of adding or updating a key more verbose.

How do I handle arrays, deletion, and nested keys in a lean way with HTTP PATCH?

Best Answer

The spec clearly details how to format the JSON body of a PATCH request. You're using a totally different format. Given that, I'm not surprised at all that there is ambiguity. The body should look something like:

   [
     { "op": "replace", "path": "/name", "value": "SimpleGuy" },
     { "op": "add", "path": "/email", "value": "hey@google.com" },
     { "op": "replace", "path": "/city", "value": null },
     { "op": "replace", "path": "/roles", "value": [ "owner" ] },
     { "op": "add", "path": "/posts/02/title", "value": "how to pop lock" },
     { "op": "add", "path": "/posts/", "value": "03" },
     { "op": "add", "path": "/posts/03/title", "value": "how to salsa" },
     { "op": "add", "path": "/notes", "value": { "title": "a note title" } }
   ]

Go back and read the spec. It even gives examples which address most of your questions.

Related Solutions

What’s the difference between a POST and a PUT HTTP REQUEST

HTTP PUT:

PUT puts a file or resource at a specific URI, and exactly at that URI. If there's already a file or resource at that URI, PUT replaces that file or resource. If there is no file or resource there, PUT creates one. PUT is idempotent, but paradoxically PUT responses are not cacheable.

HTTP 1.1 RFC location for PUT

HTTP POST:

POST sends data to a specific URI and expects the resource at that URI to handle the request. The web server at this point can determine what to do with the data in the context of the specified resource. The POST method is not idempotent, however POST responses are cacheable so long as the server sets the appropriate Cache-Control and Expires headers.

The official HTTP RFC specifies POST to be:

Annotation of existing resources;
Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;
Providing a block of data, such as the result of submitting a form, to a data-handling process;
Extending a database through an append operation.

HTTP 1.1 RFC location for POST

Difference between POST and PUT:

The RFC itself explains the core difference:

The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI, it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request.

Additionally, and a bit more concisely, RFC 7231 Section 4.3.4 PUT states (emphasis added),

4.3.4. PUT

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.

Using the right method, unrelated aside:

One benefit of REST ROA vs SOAP is that when using HTTP REST ROA, it encourages the proper usage of the HTTP verbs/methods. So for example you would only use PUT when you want to create a resource at that exact location. And you would never use GET to create or modify a resource.

Rest – the difference between POST and PUT in HTTP

Overall:

Both PUT and POST can be used for creating.

You have to ask, "what are you performing the action upon?", to distinguish what you should be using. Let's assume you're designing an API for asking questions. If you want to use POST, then you would do that to a list of questions. If you want to use PUT, then you would do that to a particular question.

Great, both can be used, so which one should I use in my RESTful design:

You do not need to support both PUT and POST.

Which you use is up to you. But just remember to use the right one depending on what object you are referencing in the request.

Some considerations:

Do you name the URL objects you create explicitly, or let the server decide? If you name them then use PUT. If you let the server decide then use POST.
PUT is defined to assume idempotency, so if you PUT an object twice, it should have no additional effect. This is a nice property, so I would use PUT when possible. Just make sure that the PUT-idempotency actually is implemented correctly in the server.
You can update or create a resource with PUT with the same object URL
With POST you can have 2 requests coming in at the same time making modifications to a URL, and they may update different parts of the object.

An example:

I wrote the following as part of another answer on SO regarding this:

POST:

Used to modify and update a resource
POST /questions/<existing_question> HTTP/1.1
Host: www.example.com/
Note that the following is an error:
POST /questions/<new_question> HTTP/1.1
Host: www.example.com/
If the URL is not yet created, you should not be using POST to create it while specifying the name. This should result in a 'resource not found' error because <new_question> does not exist yet. You should PUT the <new_question> resource on the server first.

You could though do something like this to create a resources using POST:
POST /questions HTTP/1.1
Host: www.example.com/
Note that in this case the resource name is not specified, the new objects URL path would be returned to you.

PUT:

Used to create a resource, or overwrite it. While you specify the resources new URL.

For a new resource:
PUT /questions/<new_question> HTTP/1.1
Host: www.example.com/
To overwrite an existing resource:
PUT /questions/<existing_question> HTTP/1.1
Host: www.example.com/