Meta

This API tries to follow JSON:API as close as possible but breaks the rules where it helps improving the DX, for example, patching related datasets via the parent route. Something that is fully implemented according to the spec is including related resources in responses, sorting and filtering resource lists as well as paginating them.

Includes

Resources that can be requested with their parent resources in a resource key called relations are called includes. They can be specified via the query parameter include with the value being a comma separated list.

Example: The Organizer allows including the related OrganizerTypes with the include name types which can hence be requested with: http://beta.api.kulturdaten.berlin/v1/organizer?include=types.

Sorting

Resource indexes can be sorted. This is possible with the query parameter sort with the value being one of the resource type specific orderables. The orderable name can be prefixed with - to sort in descending order with ascending order being the default.

Example: Organizers can be sorted by their creation date: http://beta.api.kulturdaten.berlin/v1/organizer?sort=createdAt.

Filtering

Resource indexes can also be filtered via the query parameter filter. Similiar to the sorting functionality, filtering is done by named, chainable filter specs. The value of filter is hence a comma-separated list.

Example: Organizers can be filtered by their state. To only retrieve published organizers one could call: http://beta.api.kulturdaten.berlin/v1/organizer?filter=published.

Pagination

Index routes are paginated by default with a page size of 1000 items. To retrieve smaller chunks of data this can be altered with the size query parameter which needs to be a valid page number.

Information about the available pages is included in the meta.pages response key which might look like this:

{
  "pages": {
    "total": 265,
    "perPage": 1000,
    "currentPage": 1,
    "lastPage": 1
  }
}