Messages¶

A message is a request sent from a CLIENT to a SERVER, or a response sent from a SERVER to a CLIENT.

CLIENTS and SERVERS MUST include the header Content-Type: application/vnd.api+json without any media type parameters to all messages that include a body. This requirement is designed to accommodate future versions and extensions of JSON:API.

All data exchanged between CLIENTS and SERVERS MUST be in the JSON format conforming to the link:https://jsonapi.org/format/1.0/JSON:API v1.0 standard.

All messages containing a body MUST be encoded in UTF-8.

Messages can be either request messages, success messages, or error messages. The remainder or this section describes the details of each.

Request Messages¶

Requests sent from a CLIENT to a SERVER are referred to as request messages.

A CLIENT MUST include the header Accept: application/vnd.api+json at least once and without any media type parameters in all requests to a SERVER to represent that the expected response MUST be conformant to this standard.

A SERVER MAY support additional media types, such as application/json and application/xml, but their adoption is not regulated by this standard.

GET /2022-04/events HTTP/1.1
Accept: application/vnd.api+json

GET /2022-04/events HTTP/1.1
Accept: application/vnd.api+json, application/vnd.api+json;modified-parameter=value, application/json

Depending on the related request, a CLIENT MAY include a JSON body on a request message (see ???). This body MUST contain one of the following fields:

data: a resource object the CLIENT wishes to create or update. The field MUST is present in certain successful CLIENT requests and SERVER responses (see ???).

When present, a CLIENT MAY include the following fields to a request message:

jsonapi: an object describing the JSON:API v1.0 the message it complies to. This field is OPTIONAL and, if set, it MUST be equal to the following object:
```
{
  "version": "1.0"
}
```

The examples below present the basic structure of a request message which varies according to the context they are used in, as described in ???.

GET /2022-04/events HTTP/1.1
Accept: application/vnd.api+json

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

{ "jsonapi": { "version": "1.0" }, "data": { "id": …, "type": "events", … } }

A CLIENT MUST NOT include additional fields in data messages, such as links, meta, or included.

A SERVER MUST reject requests including a body when it is not supported (see ???).

A SERVER SHOULD ignore additional fields sent by a CLIENT on a data message.

Success Messages¶

Successful responses sent from a SERVER to a CLIENT are referred to as success messages.

A success message header MUST contain an HTTP status code in the class https://tools.ietf.org/html/rfc7231#section-6.32xx Success, as in:

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

Depending on the related request, a SERVER MAY include a JSON body on a success message (see ???). This body MUST contain one of the following fields:

data: a field containing the resource objects to be sent to the CLIENT. The data field MUST be either:
- if the request expects a collection of resource objects in the response, the data field MUST be an array that contains the expected resources or is empty
- if the request expects a single resource object in the response, the data field MUST be a single resource object or null
  
  For details on the different types of resources in this standard and their inner structure, refer to ???.
links: an object containing links for navigating the API. Examples of links include self-referencing links, links to resources in relationships, pagination links (see ???), and hypermedia links (see ???).

Besides the root of a message, the links object MUST also be present in the root of resource objects and in relationships of resources when these are sent from a SERVER to a CLIENT. Refer to ??? for more details.
meta: an object containing the message’s metadata. Examples of metadata include the number of resources available in a certain route (see the count and page fields in ???).

When present, a SERVER MAY include the following fields to a success message:

jsonapi: an object describing the JSON:API v1.0 the message it complies to. This field is OPTIONAL and, if set, it MUST be equal to the following object:
```
{
  "version": "1.0"
}
```
included: an array of resource objects listed in selected relationships of the resources present in the data field. This field is optional but non-nullable.

See ??? for more details on the resource inclusion feature.

Success messages SHALL NOT have fields in addition to those listed above.

The example below presents the basic structure of a success message from a SERVER to a CLIENT. The structure of messages vary according to the context they are used, as described in ???.

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": { ... },
  "links": { ... },
  "data": [ ... ],
  "included": [ ... ]
}

A SERVER MUST reply with specific status codes in the following cases:

200 OK: when the CLIENT’s request has been successfully processed, with the exceptions of:
- creation requests
- deletion requests
201 Created: when the CLIENT’s creation request has been successfully processed
204 No Content: when the CLIENT’s deletion request has been successfully processed

Error Messages¶

An error message results from an unsuccessful request made to a SERVER, regardless of the different contexts detailed in ???.

An error message header MUST contain an HTTP status code either in the class \https://tools.ietf.org/html/rfc7231#section-6.5[Client Error 4xx] or the class \https://tools.ietf.org/html/rfc7231#section-6.6[Server Error 5xx], as in:

HTTP/1.1 401 Unauthorized

If a request message results in multiple errors, the returned status code MUST be the most general status code applicable. For example, if a request results in the errors 415 Unsupported Media Type and 410 Gone, the header SHOULD contain the error code 400 Bad Request.

A SERVER MAY include a body in an error message. If it does, this body MUST contain one of the following fields:

errors: an array of link:https://jsonapi.org/format/1.0/#error-objectserror objects as defined in JSON:API v1.0. This field cannot be empty.
links: an object containing links (see ???). This field must contain a self link contain the route present in the CLIENT’s.

When present, a SERVER MAY include the following fields to a error message:

jsonapi: an object describing the JSON:API v1.0 the message is complies to. This field is OPTIONAL and, if set, it MUST be equal to the following object:
```
{
  "version": "1.0"
}
```
meta: an object that contains non-standard meta-information about its container. This field is OPTIONAL but cannot be empty.

Error messages SHALL NOT have fields in addition to those listed above.

An overview of the basic structure of an error message body is depicted below:

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": { ... },
  "errors": [
    {
      "status": "404",
      "title": "Endpoint not available"
    }
  ],
  "links": { ... }
}

The following example presents an error message (header and body) containing multiple error objects.

HTTP/1.1 404 Not Found
Content-Type: application/vnd.api+json

{ "jsonapi": { "version": "1.0" }, "errors": [ { "status": 404, "title": "Resource not found." }, { "status": 405, "title": "Method not supported." } ] }

A SERVER MUST reply with specific status codes in the following cases:

400 Bad Request: when a CLIENT makes a request containing:
- a method body when it is not supposed to (see ???)
- a query parameter not defined in this standard
- a query parameter not supported for the specific request
- a query parameter with an incorrect value
- conflicting query parameters
- a method that does not comply the standard’s definitions
- a method that requests the creation of a resource with an id that is already used or malformed
- a creation or update of a resources' relationship referring to a resource that does not exist
401 Unauthorized: when a CLIENT makes a request:
- using an authentication method, but the credentials fail to be validated by the SERVER
- without an authentication method, but the SERVER does not accept such requests
404 Not Found: when a CLIENT makes a request:
- to an endpoint not defined in this standard
- to a non-implemented endpoint
- asking for a non-existing resource
- asking for a non-existing page number
405 Method Not Allowed: when a CLIENT makes a request using an HTTP method that is not supported by the SERVER.
406 Not Acceptable: when a CLIENT makes a request with an Accept header containing a media type not supported by the SERVER or with encoding parameters in application/vnd.api+json.