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 apage[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. Thenext
URL MUST be the same aslast
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. Theprev
URL MUST be the same asfirst
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 asort
and arandom
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 forsort
: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 asfilter[FILTER-NAME]=VALUES
, whereVALUES
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 patternfilter[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 notnull
). Accepts as argument a singletrue
orfalse
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 singleboolean
,number
, orstring
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 singleboolean
,number
, orstring
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 ofnumber
orstring
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 ofnumber
orstring
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 ofnumber
orstring
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 ofnumber
orstring
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 singlenumber
orstring
.
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 singlenumber
orstring
.
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 singlenumber
orstring
.
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 singlenumber
orstring
.
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 threenumber
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 singlestring
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 singlestring
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 singlestring
.
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 singlestring
.
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 singlestring
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
anddescription
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 multiplefield[]
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 }] }
Inclusion of Related Resources¶
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 themeta
object of the resource being created -
A SERVER MAY assign the
dataProvider
value in themeta
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 themeta
object of the resource being updated -
A SERVER MAY assign the
dataProvider
value in themeta
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