Skip to content

Resource Update

A SERVER MAY support resource update requests.

If implemented, a SERVER MUST treat resource update requests as transactions, i.e., requests MUST either fully succeed or fail entirely leaving no partial side-effects.

Resource update requests MUST be performed through HTTP PATCH requests (see ???).

Resource update requests MUST be supported on individual resource routes (see ???) of the identified resource.

Resource update requests MUST include Content-Type and Accept headers.

Resource update requests MUST include a JSON body containing a data field, as described in ???.

Resource update requests MUST include the resource to be updated in the data field of the body’s message.

Resource update requests MUST include the id and the type of the resource to be updated and these values MUST conform to the individual resource route the request was sent to.

Resource update requests MUST include all attributes and relationships to be replaced. Attributes and relationships that are to be removed MUST be set to null. Non-nullable attributes and relationships MUST NOT be set to null.

A SERVER MUST reject resource update requests that do not conform to the requirements defined here.

The example below demonstrates a valid resource update request to update an event resource.

PATCH /2020-04/events/123 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{ "data": { "type": "events", "id": "123", "attributes": { "status": "canceled" }, "relationships": { "publisher": { "data": { "type": "agents", "id": "2" } }, "sponsors": null } } }

A SERVER MUST respond to successful requests with a status code 200 OK.

A SERVER MUST add the Content-Type header on successful responses (see ???).

In the success response the SERVER MUST send the created resource, including all fields of the attributes, relationships, meta, and links (see ???) objects, equal to a retrieval request on the created resource’s individual route.

A SERVER MUST set the value of lastUpdate in the meta object of the resource to the moment when the resource was updated.

A SERVER SHOULD ignore any additional fields included in the request (see ???).

A SERVER SHOULD ignore any links objects present in the request (see ???).

A SERVER MUST reject creation requests whose resource contains relationships to resources that do not exist in the SERVER.

A SERVER MAY update the value of the dataProvider field of the meta object of the resource using one of the following options:

  • A SERVER MAY keep the dataProvider value of the creation assigned during the creation of the resource

  • A SERVER MAY require CLIENTS to send the dataProvider value in the meta object of the resource being updated

  • A SERVER MAY assign the dataProvider value in the meta object of the resource using information from outside the message’s body (e.g., using the authentication of the request to identify the data provider)

If a SERVER does not use CLIENT-generated values for dataProvider, or does not update the value of dataProvider after the resource’s creation, it MUST reject update requests that include a value for dataProvider.

The following example demonstrates the response to a successful resource update request.

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{ "jsonapi": { …​ }, "links": { …​ }, "meta": { …​ }, "data": { "type": "events", "id": "123", "meta": { …​ }, "attributes": { "status": "canceled", …​ }, "relationships": { "publisher": { "data": { "type": "agents", "id": "2" }, "links": { "related": …​ } }, "sponsors": null …​ } } }

A SERVER MUST reply to resource update requests with an error response in the following cases, using the adequate error codes (see ???).

  • The CLIENT does not have authorization to update the resource

  • The PATCH HTTP method is not implemented in the requested route

  • The request does not include a well-formed resource in the message’s body

  • The request updates non-nullable fields to null