8

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?

Combo
  • 855
  • 2
  • 11
  • 22
  • 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

1 Answers1

9

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.

Community
  • 1
  • 1
cassiomolin
  • 124,154
  • 35
  • 280
  • 359
  • 3
    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, this is how it should be in HTTP, not in REST – Combo Apr 04 '18 at 13:53
  • @Combo Aren't you implementing REST over HTTP? – cassiomolin Apr 04 '18 at 13:57
  • 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
  • 3
    @Combo Do you have any references to support it? – cassiomolin Apr 04 '18 at 14:42