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 Retrieval¶

Pagination¶

Sorting¶

Random sorting¶

Filtering¶

Searching¶

Sparse Fieldsets¶

Inclusion of Related Resources¶