Backend API conventions

Last updated:
Edit on GitHub

Every Backend API resource follows the same conventions for authorization headers, pagination, filtering, and sorting. This page describes them once. Individual resource guides list only what is specific to that resource—the filterable properties, the sortable fields, and the attributes.

These conventions are JSON:API as implemented by API Platform, not a Spryker invention: page[limit]/page[offset], the filter[…] family, the sort parameter with its - prefix, and the first/last/prev/next link set all come from that stack. The one Spryker-specific part is the shape of the meta.pagination object, which keeps the keys the legacy Glue REST API returned.

Request headers

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.
Content-Type application/vnd.api+json ✓ for requests with a body Media type of the request body. Required for POST, PATCH, and PUT.
Accept application/vnd.api+json Media type of the response. If you omit this header, the endpoint answers with application/vnd.api+json.

A request without a valid access token returns 401.

Pagination

Pagination, the meta.pagination summary, and the pagination links are described in Resource schemas — Pagination.

One behaviour is worth knowing at the call site: a request for a page beyond the last one serves the last page and reports it as the current page, rather than returning an empty collection.

Filtering and sorting

Filtering uses the JSON:API filter parameter family and sorting the sort parameter, with a - prefix for descending order. Each resource declares which properties it supports—see the resource’s own guide.

JSON:API reserves the filter name but leaves its contents to the implementation. Spryker qualifies every filter key with the resource name, so a filter on a related resource is unambiguous:

filter[{resource}.{property}]={value}

For example, filter[companies.name]=acme. A key without the resource prefix returns 400 with the error code 011, and a filter addressing an unsupported property returns 400 with the error message naming the properties that are supported. An unsupported sort field returns 400 with the error code 1203.

Collections are ordered deterministically, so paging through one never repeats or skips an item.

Errors

Each resource guide lists the error codes specific to that resource. For the response shape and the codes shared by every API, see API errors and troubleshooting.