Skip to content

Resource Creation

A SERVER MAY support resource creation requests.

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

Resource creation requests MUST be performed through HTTP POST requests (see ???).

Resource creation requests MUST be supported on resource collection routes (see ???) of the intended resource type.

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

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

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

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

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

POST /2022-04/events HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{ "data": { "type": "events", "id": "123", "attributes": { "name": { "eng": "Südtirol Jazz Festival 2022" }, "startDate": "2022-06-29T00:00:00+00:00", "status": "published" }, "relationships": { "publisher": { "data": { "type": "agents", "id": "1" } } } } }

A SERVER MUST respond to successful requests with a status code 201 CREATED.

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

A SERVER SHOULD add the Location header with the individual resource route of the created resource.

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 created.

A SERVER MUST assign a value to the dataProvider field of the meta object of the resource using one of the following options:

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

  • 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, it MUST reject creation requests that include a value for dataProvider.

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 does not include a valid resource type, type, or whose resource lacks any non-nullable fields (see ???).

A SERVER MUST set to null any nullable attribute or relationship that is not present in the creation request’s resource (see ???).

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

A SERVER MUST accept CLIENT-generated values of id as long as the conditions below are meet. Otherwise, the SERVER MUST reject the request.

  • the id is available in the SERVER

  • the id conforms to the syntax used by the SERVER

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

HTTP/1.1 201 CREATED
Content-Type: application/vnd.api+json
Location: \https://example.com/2022-04/events/123

{ "jsonapi": { …​ }, "links": { …​ }, "meta": { …​ }, "data": { "type": "events", "id": "123", "links": { "self": …​ }, "meta": { "lastUpdate": …​, "dataProvider": …​, }, "attributes": { "name": { "eng": "Südtirol Jazz Festival 2022" }, "startDate": "2022-06-29T00:00:00+00:00", "status": "published", "description": null, …​ }, "relationships": { "publisher": { "data": { "type": "agents", "id": "1" }, "links": { "related": …​ } }, "venues": null, …​ } } }

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

  • the CLIENT does not have authorization to create a resource

  • the POST 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 lacks non-nullable fields

  • the request includes an invalid CLIENT-generated id