PATCH in REST and null

Question

We have an article resource with properties:

title
image
description
status: published | draft

if we want only to remove image we make request

{title: null, image: null, description: null, status: null}

if we want only to update status we make request

{title: null, image: null, description: null, status: draft}

but in this case image also will be removed

How in REST to update only one property?

Check zbateson response: https://stackoverflow.com/questions/38424383/how-to-distinguish-between-null-and-not-provided-values-for-partial-updates-in-s — user666, Feb 21 '22 at 08:30

score 9 · Answer 1 · edited Oct 07 '21 at 07:59

Performing partial modifications to a resource

The PATCH method can be used to perform partial modifications to a resource. The request payload should contain a set of instructions describing how the resource will be modified. See the following quote from the RFC 5789:

2. The PATCH Method

The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI. [...]

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. [...]

To describe such set of instructions, you can use JSON Patch defined in the RFC 6902:

1. Introduction

JSON Patch is a format (identified by the media type application/json-patch+json) for expressing a sequence of operations to apply to a target JSON document; it is suitable for use with the HTTP PATCH method.

This format is also potentially useful in other cases in which it is necessary to make partial updates to a JSON document or to a data structure that has similar constraints [...]

Examples with JSON Patch

To update the status, you can do the following:

PATCH /articles/1 HTTP/1.1
Host: example.com
Content-Type: application/json-patch+json

[
  { "op": "replace", "path": "/status", "value": "draft" }
]

Use the following to remove the image:

PATCH /articles/1 HTTP/1.1
Host: example.com
Content-Type: application/json-patch+json

[
  { "op": "remove", "path": "/image" }
]

And use the following to update the status and remove the image:

PATCH /articles/1 HTTP/1.1
Host: example.com
Content-Type: application/json-patch+json

[
  { "op": "replace", "path": "/status", "value": "draft" },
  { "op": "remove", "path": "/image" }
]

Alternatively to JSON Patch, you may want to consider JSON Merge Patch defined in the RFC 7396: it's also a means of describing a set of modifications to a target resource's content.

I thought in REST, PATCH payload should has same structure as POST/PUT — Combo, Apr 04 '18 at 12:33
@Combo From the RFC 5789: _The `PATCH` method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI._ — cassiomolin, Apr 04 '18 at 13:26
Yes, it is over, but this doesn't mean it must be implemented the same, Java is also implemented over assembly, but this doesn't mean if assembly does not have classes Java also must not implement them — Combo, Apr 04 '18 at 14:09
@Combo Your comparison makes no sense. Once you are implementing REST over HTTP, you should follow the semantics of the HTTP methods you are using. — cassiomolin, Apr 04 '18 at 14:32
yes, semantic, but not syntax, in REST, PATCH payload should has same structure as POST/PUT — Combo, Apr 04 '18 at 14:41

score 0 · Answer 2 · answered Oct 09 '19 at 07:38

Let me give an example which troubles me when using JSON-Patch message in PATCH message in a RESTFul API. If we have a structure like:

{"books": [
   {"title": "HTTP-Protocol", "image": "http.jpg", "description": "A standard book on HTTP", "status": "Available"},
   {"title": "JSON-Patch", "image": "patching.jpg", "description": "Explanation on how to use json-patch in RESTFul", "status": "Planned"},
   {"title": "RESTFul", "image": "fielding.jpg", "description": "Representational state transfer", "status": "Available"}
]}

Now the client who requested this information wants to change the status of the third book (RESTFul) from "Available" to "Borrowed". Using JSON-Patch he would send the following message:

[
    {
        "op": "replace",
        "path": "/books/2/status",
        "value": "Borrowed"
    }
]

Meaning that from the list, as he saw it, he wants to change the status of the third item. But since a RESTFul API call is stateless the server does not know anymore what list it gave to the client. Maybe in the mean time a new book was added and the list on the server change to:

{"books": [
   {"title": "HTTP-Protocol", "image": "http.jpg", "description": "A standard book on HTTP", "status": "Available"},
   {"title": "In between", "image": "destroy.jpg", "description": "Not RESTFul?", "status": "Available"},
   {"title": "JSON-Patch", "image": "patching.jpg", "description": "Explanation on how to use json-patch in RESTFul", "status": "Planned"},
   {"title": "RESTFul", "image": "fielding.jpg", "description": "Representational state transfer", "status": "Available"}
]}

Then this json-patch message received from the client will change the book with the title "JSON-Patch" and not the book with title "RESTFul" as intended by the client.

What is in your opinion the solution for this problem?

The problem here is that your resource's identity can shift around. If your resource's identify could be `/books/json-patch` then that would solve it (or its ID could be an ever-incrementing database ID, same principle) — Jon Lauridsen, Sep 26 '20 at 11:29

PATCH in REST and null

2 Answers2

Performing partial modifications to a resource

Examples with JSON Patch