Requests and Responses¶

This chapter defines the different interactions between CLIENTS and SERVERS for the creation, retrieval, update, and deletion of data.

Resource Retrieval¶

A CLIENT MAY retrieve links and resource objects from a SERVER through an HTTP GET request. The GET request MUST be performed on the route corresponding to the desired resource(s) (see ???).

The following example demonstrates a GET request for the retrieval of resources available on the events route (see ???), including also an authorization header.

GET /2022-04/events HTTP/1.1
Host: https://example.com
Accept: application/vnd.api+json
Authorization: Basic Y2hyaXM6c2VjcmV0

A CLIENT MUST NOT include a Content-Type header on retrieval requests. A CLIENT MUST NOT include a body on retrieval requests.

If a CLIENT’s retrieval request includes a body or includes invalid headers, the SERVER MUST respond with the corresponding error code (see ???).

If the route requested by a CLIENT on a retrieval request is implemented by a SERVER, it MUST respond to successful requests with data corresponding available data. The SERVER response to a successful request MUST include the status code 200 OK. The SERVER response to a successful request MUST include the header Content-Type.

The example below demonstrates a valid request for the retrieval of a collection of agent resources (see events).

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

{
   "jsonapi": { ... },
   "meta": { ... },
   "links": { ... },
   "data": [
      {
         "type": "events",
         "id": "1",
         "meta": { ... },
         "attributes": { ... },
         "relationships": { ... },
         "links": { ... }
      }
   ]
}

The AlpineBits® standard specifies a set of API features to be implemented by a SERVER. These features are intended to make data retrieval requests from CLIENTS to SERVERS more effective and efficient (see Resource Retrieval).

The list of features is as follows: Pagination, Sorting, Random sorting, Filtering, Searching, Sparse Fieldsets, and Inclusion of Related Resources.

Pagination¶

The pagination feature allows CLIENTS to request a subset of a resource collection.

A SERVER MUST implement page-based pagination on retrieval requests for all resource collection routes (see ???).

The response message containing such a subset is called a page.

The pagination strategy adopted in this standard uses two parameters:

page[size]: the number of resources included in a page.
page[number]: the number of the page.

The following request message exemplifies the use of pagination parameters:

GET /2022-04/events?page[size]=10&page[number]=2 HTTP/1.1
Host: https://example.com
Accept: application/vnd.api+json

The request asks for the second page (page[number]=2) in the collection of event resources, divided into pages containing 10 events each (page[size]=10).

A SERVER that implements pagination MUST:

Be able to handle requests containing just a page[size] query parameter, just a page[number], or both.
Support pagination for GET requests in every base endpoint, such as /2022-10/events and /2022-10/mountainAreas.
Respond with the first page if no pagination parameters are sent in the request.
In paginated responses, add the following fields to the links object in the message body:
- first: a string that represents the URL to request the first page of resources in that endpoint. Non-nullable.
- last: a string that represents the URL to request the last page of resources in that endpoint. Non-nullable.
- self: a string that represents the URL to request the current page of resources in that endpoint. Non-nullable.
- next: a string that represents the URL to request the next page of resources in that endpoint. The next URL MUST be the same as last in case the next page is out of bounds. Non-nullable.
- prev: a string that represents the URL to request the previous page of resources in that endpoint. The prev URL MUST be the same as first in case the previous page is out of bounds. Non-nullable.
```
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "first": "https://example.com/2022-04/events?page[number]=1",
    "last": "https://example.com/2022-04/events?page[number]=100",
    "self": "https://example.com/2022-04/events?page[number]=2",
    "next": "https://example.com/2022-04/events?page[number]=3",
    "prev": "https://example.com/2022-04/events?page[number]=1"
  },
  ...
}
```
In paginated responses, add the following fields to the meta object in the message body:
- count: a number that indicates the number of resources available in the endpoint. Non-nullable.
- pages: a number that indicates the number of pages in the resource collection given the selected page size. Non-nullable.
```
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "meta": {
    "count": 1000,
    "pages": 100
  },
  ...
}
```

Respond a request for a non existing page with an error message whose status code is 404 Not Found.

GET /2022-04/events?page[number]=10000 HTTP/1.1
Host: https://example.com
Accept: application/vnd.api+json

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

A SERVER that implements pagination SHOULD:

Define a default page size.

Respond a request for a non existing page with an error message containing a body as follows:

GET /2022-04/events?page[number]=10000 HTTP/1.1
Host: https://example.com
Accept: application/vnd.api+json

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

{
  "error": [
    {
      "status": "404",
      "title": "Page not found"
    }
  ],
  "links": {
    "self": "http://example.com/2022-04/events?page[number]=10000"
  }
}

Sorting¶

A SERVER SHOULD support requests to sort resource collections according to one or more criteria (sort fields), as defined in the JSON:API v1.0 specification.

A SERVER that implements this feature MUST:

Interpret the values of the sort query parameter as sort fields:

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

Interpret a sort field to be ascending unless it is preceded by a minus (U+002D HYPHEN-MINUS, "-"), in which case it MUST interpret it to be descending:
```
GET /2022-04/events?sort=-name HTTP/1.1
Accept: application/vnd.api+json
```
Interpret a dot-separated (U+002E FULL-STOP, ".") sort field to be a request to sort by a relationship or a nested attribute:
```
GET /2022-04/events?sort=organizer.name HTTP/1.1
Accept: application/vnd.api+json
```

Respond with a 400 Bad Request if a request contains a sort field that is not supported by the SERVER:

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

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "https://example.com/2022-04/events?sort=hello",
  },
  "errors": [{
      "title": "Invalid query parameter value.",
      "status": 400
  }]
}

A SERVER that implements sorting SHOULD:

Adopt sort fields that correspond to resource attributes:

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

Support sorting by combining multiple sort fields:

GET /2022-04/events?sort=name,startDate HTTP/1.1
Accept: application/vnd.api+json

A SERVER that implements sorting MAY:

Adopt sort fields that do not correspond to resource attributes and relationships.
```
GET /2022-04/events?sort=date HTTP/1.1
Accept: application/vnd.api+json
```

Random sorting¶

A SERVER MAY support requests to randomly sort resource collections according to a seed value.

A SERVER that implements this feature MUST:

Interpret the value of the random query parameter as the seed to be used to sort the resource collection:
```
GET /2022-04/events?random=5 HTTP/1.1
Accept: application/vnd.api+json
```
Always return resources in the same order for requests using a given seed value, provided everything else remains the same (e.g. the resource collection, the page size, and the page number)

Respond with a 400 Bad Request if a request combines a sort and a random query parameter:

GET /2022-04/events?random=5&sort=startDate HTTP/1.1
Accept: application/vnd.api+json

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "https://example.com/2022-04/events?random=5&sort=startDate",
  },
  "errors": [{
      "title": "Request contains conflicting queries.",
      "status": 400
  }]
}

Respond with a 400 Bad Request if a request includes a seed value that is not supported by the SERVER:

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

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "https://example.com/2022-04/events?random=hello",
  },
  "errors": [{
      "title": "Invalid query parameter value.",
      "status": 400
  }]
}

A SERVER that implements random sorting SHOULD:

Allow a CLIENT to combine random with every other query parameter defined in this document, except for sort:

GET /2022-04/events?random=12&fields[events]=name,startDate&page[size]=30&page[number]=2 HTTP/1.1
Accept: application/vnd.api+json

Filtering¶

A SERVER SHOULD support filtering over its resources.

This standard specifies two strategies for filtering, label-specific filters and simple generic filters:

Label-specific filter: the SERVER defines the name of each supported filter, its semantics, and the values it may receive. Label-specifics filters MUST be defined as filter[FILTER-NAME]=VALUES, where VALUES may be a list of comma-separated values.

For instance, a filter for resources updated after 01/01/2021 could be defined as follows:
```
GET /2022-04/events?filter[lastUpdate]=2021-01-01 HTTP/1.1
Accept: application/vnd.api+json
```
Simple generic filter: this standard defines a list of generic filter operands, their semantics, and the values it may receive. These filters are then requested over resources' fields following the pattern filter[FIELD][OPERAND]=VALUES.

For instance, a request to retrieve events starting after 01/01/2021 is defined as follows.
```
GET /2022-04/events?filter[startDate][gt]=2021-01-01 HTTP/1.1
Accept: application/vnd.api+json
```

A SERVER is RECOMMENDED to support filtering over the following data:

Last update
Language
Categories
Date (events)
Publisher (events)
Location (geolocation or address based)
Length (ski slopes, snowparks)
Opening schedule - open at (places open on a certain date)
Difficulty (ski slopes, snowparks)
Snow conditions (mountain areas, snowparks)
Area owner (mountain areas)

A SERVER MAY support multiple filters in a single request.

A SERVER MUST reply to requests with non-supported filters, field names, or values with 400 Bad Request status code:

GET /2022-04/events?filter[foo]=bar HTTP/1.1
Accept: application/vnd.api+json

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json
{
  "links": {
    "self": "https://example.com/2022-04/events?filter[foo]=bar",
  },
  "errors": [{
      "title": "Invalid query parameter value.",
      "status": 400
  }]
}

A SERVER MAY support custom filters, i.e., those that are cannot be expressed as simple generic filters, as label-specific filters: For example, a filter retrieves events "active" in between two dates:

+

GET /2022-04/events?filter[between]=2021-03-01,2021-03-10 HTTP/1.1
Accept: application/vnd.api+json

A SERVER SHOULD prefer simple generic filters over label specific filters.

A SERVER MAY support simple generic filters over nested fields. For example, a filter over the countries in venues' addresses:

+

GET /2022-04/venues?filter[address.country][eq]=IT HTTP/1.1
Accept: application/vnd.api+json

The standard defines the following list of operands for simple generic filters:

exists: filters resources that according to whether or not the field has values (i.e., it is not null). Accepts as argument a single true or false value.
For example, filter event resources that have multimedia descriptions:
```
GET /2022-04/events?filter[multimediaDescriptions][exists]=true HTTP/1.1
Accept: application/vnd.api+json
```
eq: filters resources that have the field assigned to a specific value. Accepts as argument a single boolean, number, or string value.
For example, filter venue resources whose address has a specific country value:
```
GET /2022-04/venues?filter[address.country][eq]=IT HTTP/1.1
Accept: application/vnd.api+json
```
neq: filters resources that have the field not assigned to a specific value. Accepts as argument a single boolean, number, or string value.
For example, filter snowpark resources whose difficulty level is not "expert":
```
GET /2022-04/snowparks?filter[difficulty][neq]=expert HTTP/1.1
Accept: application/vnd.api+json
```
in: filters resources that have the field assigned to values within a desired list. Accepts a list of number or string arguments.
For example, filter snowpark resources whose difficulty is within the list [ "beginner", "intermediate" ].
```
GET /2022-04/snowparks?filter[difficulty][in]=beginner,intermediate HTTP/1.1
Accept: application/vnd.api+json
```
nin: filters resources that have the field not assigned to values within a desired list. Accepts a list of number or string arguments.
For example, filter snowpark resources whose difficulty is not within the list [ "advanced", "expert" ].
```
GET /2022-04/snowparks?filter[difficulty][nin]=advanced,expert HTTP/1.1
Accept: application/vnd.api+json
```
any: filters resources that have some of the field’s values within a desired list. Accepts a list of number or string arguments.
For example, filter event resources whose categories include some of the values in the list [ "schema:MusicEvent", "schema:SportsEvent" ].
```
GET /2022-04/events?filter[categories][any]=schema:MusicEvent,schema:SportsEvent HTTP/1.1
Accept: application/vnd.api+json
```
all: filters resources that have all of the field’s values within a desired list. Accepts a list of number or string arguments.
For example, filter event resources whose categories include some of the values in the list [ "schema:Festival", "schema:MusicEvent" ].
```
GET /2022-04/events?filter[categories][any]=schema:Festival,schema:MusicEvent HTTP/1.1
Accept: application/vnd.api+json
```
gt: filters resources that have the field assigned to a value greater than the desired one. Accepts as argument a single number or string.
For example, retrieve agent resources that have their last update greater than a certain date-time:
```
GET /2022-04/agents?filter[lastUpdate][gt]=2022-04-01T00:00:00+0000 HTTP/1.1
Accept: application/vnd.api+json
```
gte: filters resources that have the field assigned to a value greater than or equal to the desired one. Accepts as argument a single number or string.
For example, retrieve agent resources that have their last update greater than or equal to a certain date-time:
```
GET /2022-04/agents?filter[lastUpdate][gte]=2022-04-01T00:00:00+0000 HTTP/1.1
Accept: application/vnd.api+json
```
lt: filters resources that have the field assigned to a value lower than the desired one. Accepts as argument a single number or string.
For example, retrieve ski slope resources that have their length lower than a certain value:
```
GET /2022-04/skiSlopes?filter[length][lt]=5000 HTTP/1.1
Accept: application/vnd.api+json
```
lte: filters resources that have the field assigned to a value lower than or equal to the desired one. Accepts as argument a single number or string.
For example, retrieve ski slope resources that have their length lower than or equal to a certain value:
```
GET /2022-04/skiSlopes?filter[length][lte]=5000 HTTP/1.1
Accept: application/vnd.api+json
```
near: filters resources located within a certain distance to a pair of coordinates. Accepts three number arguments representing a coordinate’s longitude and latitude, and a distance in meters (i.e., LONGITUDE,LATITUDE,DISTANCE).
For example, retrieve lift resources whose geometries are within 10000 meters geo-located pair of longitude and latitude (11.891472,46.92275):
```
GET /2022-04/lifts?filter[geometries][near]=11.891472,46.92275,10000 HTTP/1.1
Accept: application/vnd.api+json
```
intersects: filters resources whose geo-location data intersects a desired area. Accepts as argument a single string representing a GeoJSON object of type "Polygon" (see ???).
For example, filter mountain areas whose geometry intersects a specific area (e.g., the area surrounding a mountain).
```
GET /2022-04/mountainAreas?filter[geometries][intersects]={"type":"Polygon","coordinates": [[11.3490,46.4976],[11.3508,46.4975],[11.3510,46.4989],[11.3492,46.4990]]]} HTTP/1.1
Accept: application/vnd.api+json
```
within: filters resources whose geo-location data is within a desired area. Accepts as argument a single string representing a GeoJSON object of type "Polygon" (see ???).
For example, filter venues whose geometry is within a specific area.
```
GET /2022-04/venues?filter[geometries][within]={"type":"Polygon","coordinates": [[11.3490,46.4976],[11.3508,46.4975],[11.3510,46.4989],[11.3492,46.4990]]]} HTTP/1.1
Accept: application/vnd.api+json
```
starts: filters resources whose text field starts with a desired substring. Accepts as argument a single string.
For example, filter media object resources whose content type string start with a certain substring:
```
GET /2022-04/mediaObjects?filter[contentType][starts]=video HTTP/1.1
Accept: application/vnd.api+json
```
ends: filters resources whose text field ends with a desired substring. Accepts as argument a single string.
For example, filter media object resources whose content type string ends with a certain substring:
```
GET /2022-04/mediaObjects?filter[contentType][end]=png HTTP/1.1
Accept: application/vnd.api+json
```
regex: filters resources whose text field passes a desired regular expression. Accepts as argument a single string representing a regular expression.
For example, filter media object resources whose content type passes a certain regular expression:
```
GET /2022-04/mediaObjects?filter[contentType][regex]=^(audio|image|video) HTTP/1.1
Accept: application/vnd.api+json
```

Searching¶

A SERVER SHOULD support text search over its resources.

A SERVER that implements this feature MUST:

Interpret the value of a search[FIELD] query parameter as the string to be used to search for resources, while the value between square brackets refers to the resources' field that should be considered in the search:
```
GET /2022-04/events?search[name]=bolzano HTTP/1.1
Accept: application/vnd.api+json
```

Respond with a 400 Bad Request if a request searches for a query string on a field that does not exist on the resource types returned by the queried endpoint.

GET /2022-04/events?search[license]=bolzano HTTP/1.1
Accept: application/vnd.api+json

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "https://example.com/2022-04/events?search[license]=bolzano",
  },
  "errors": [{
      "title": "Invalid query parameter value.",
      "status": 400
  }]
}

A SERVER that implements searching SHOULD:

Support searching at least over the name and description attributes, which are defined for all resource types:
```
GET /2022-04/events?search[name]=bolzano HTTP/1.1
Accept: application/vnd.api+json
```

Allow CLIENTS to combine a search query parameter with any other query parameter defined in this standard:

GET /2022-04/events?search[name]=bolzano&page[size]=20&fields[events]=name,startDate&sort=-startDate HTTP/1.1
Accept: application/vnd.api+json

A SERVER that implements searching MAY:

Support searching over all fields of a resource type by accepting a search query parameter that is not followed by square brackets:
```
GET /2022-04/events?search=bolzano HTTP/1.1
Accept: application/vnd.api+json
```
Choose how its search feature behaves. For instance, a SERVER MAY return resources whose fields match or contain the search string, or whose fields contain a substring that is similar to the search string.

Sparse Fieldsets¶

A SERVER MAY support requests to return only specific fields that characterize a resource on a per-type basis, as defined in the JSON:API v1.0 specification.

This feature applies both to endpoints that return collections of resources, e.g. /2022-10/events, and those that return individual resources, e.g. /2022-10/events/123.

A SERVER that implements this feature MUST:

Interpret the comma-separated (U+002C COMMA, ",") values of field[TYPE] query parameters as the selected fields (attributes or relationships) to be returned for a given resource type, which in turn is identified by the value between square brackets:

GET /2022-04/agents?fields[agents]=name,contactPoints HTTP/1.1
Host: https://example.com
Accept: application/vnd.api+json

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

{
  "links": {
      "self": "https://example.com/2022-04/agents?fields[agents]=name,contactPoints",
  },
  "data": [{
      "type": "agents",
      "id": "1",
      "meta": { ... },
      "attributes": {
        "name": {
            "eng": "Free University of Bozen-Bolzano"
        },
        "contactPoints": { ... },
      },
      "relationships": null,
      "links": { ... }
  }]
}

Be able to process one field[TYPE] query parameter per resource type:

GET /2022-04/events?fields[events]=name,startDate&fields[agents]=name,contactPoints&include=organizers HTTP/1.1
Host: https://example.com
Accept: application/vnd.api+json

NOT include additional fields in resource objects if a CLIENT requests a restricted field set (using fields[]) for the respective resource types.
Send all fields for resource objects if a CLIENT does not select a restricted field set (using fields[]) for the respective resource types.
Respond with a 400 Bad Request status code a request that selects fields that do not exist for a resource type.
```
GET /2022-04/events?fields[events]=price HTTP/1.1
Accept: application/vnd.api+json
```

Respond with a 400 Bad Request status code a request that submits multiple field[] parameters for one resource type.

GET /2022-04/events?fields[events]=name&fields[events]=name,startDate HTTP/1.1
Accept: application/vnd.api+json

Respond with a 400 Bad Request status code a request that selects fields on resource types that are not returned in the queried endpoint.

GET /2022-04/events?fields[lifts]=name HTTP/1.1
Accept: application/vnd.api+json

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "https://example.com/2022-04/events?fields[lifts]=name",
  },
  "errors": [{
      "title": "Query parameter does not have valid values.",
      "status": 400
  }]
}

The inclusion of related resources feature allows a CLIENT to request a SERVER to add, in a response message, the resources related to the base resource.

For example, a CLIENT MAY request a SERVER for event resources and to include agent resources that appear in the organizers field of the events returned in the response.

An example of a request asking for related resources is shown below:

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

It is RECOMMENDED that SERVERS support the inclusion of related resources.

In successful messages, a SERVER MUST add the related resources of requested relationships to the included array.

To ask for the inclusion of related resources, a CLIENT MUST append includes as a URL parameter of the request message.

The resources to be included are listed and separated by commas, as in /2022-10/events?include=organizers,sponsors and /2022-10/mountainAreas?include=skiSlopes,lifts,snowparks.

To request resources related to other resources, a dot-separated path for each relationship name can be specified, as in /2022-10/events?include=organizers.multimediaDescriptions and /2022-10/mountainAreas?include=multimediaDescriptions.licenseHolder.

If a SERVER is unable to identify a relationship or does not support the inclusion of resources from a relationship, it MUST respond with 400 Bad Request.

The following example presents the response to a request for a collection of mediaObjects resources with of resources present in the licenseHolder relationship.

GET /2022-04/mediaObjects?include=licenseHolder HTTP/1.1
Host: https://example.com
Accept: application/vnd.api+json

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

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": { ... },
  "links": { ... },
  "data": [
    {
      "type": "mediaObjects",
      "id": "1",
      "meta": { ... },
      "links": { ... },
      "attributes": { ... },
      "relationships": {
        "categories": null,
        "licenseHolder": {
          "data": {
            "type": "agents",
            "id": "2"
          },
          "links": { ... }
        }
      }
    }
  ],
  "included": [
    {
      "type": "agents",
      "id": "2",
      "meta": { ... },
      "attributes": { ... },
      "relationships": { ... }
    }
  ]
}

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

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

Resource Deletion¶

A SERVER MAY support resource deletion requests.

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

Resource deletion requests MUST be performed through HTTP DELETE requests (see ???).

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

Resource deletion requests MUST NOT include a body, as described in ???.

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

DELETE /2022-04/events/123 HTTP/1.1

A SERVER MUST respond to successful requests with a status code 204 No Content.

A SERVER MUST NOT include a body message in responses to successful deletion requests.

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

HTTP/1.1 204 No Content

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

the resource identified by the route’s id does not exist
the CLIENT does not have authorization to delete the resource

Requests and Responses¶

Resource Retrieval¶

Pagination¶

Sorting¶

Random sorting¶

Filtering¶

Searching¶

Sparse Fieldsets¶

Inclusion of Related Resources¶

Resource Creation¶

Resource Update¶

Resource Deletion¶