Common functionality

Introduction

Many of the GET requests in the Patchworks Core API use common functionality to control the data returned. This includes the following:

Common functionality	Controls...
Filters	Which models are returned.
Fields	The fields returned within each model.
Includes	The related models returned.
Sorting	The order of the models returned.
Pagination	The number of models returned on each page

These are not available in all cases; please check the documentation for the specific endpoint needed.

Filters

Filters are used to limit the models returned to those meeting specific criteria. Filters consist of two parts: key and value, and are used in the URL as query parameters. Here is an example:

// get models where key=value AND key2=value2
/my/endpoint?filter[key]=value&filter[key2]=value2

In some cases, multiple values may be passed to a filter (for an or comparison) like so:

// get models where key IN (value, value1)
/my/endpoint?filter[key]=value,value1

Please see individual endpoints for a list of supported filters.

Fields

Some endpoints allow the user to take a more declarative approach by specifying what fields should be included in the models returned. The format is:

/my/endpoint?fields[users]=field1,field2

Most endpoints do not allow this functionality, but it is becoming more widely available over time.

Includes

Core is a highly relational system, so it makes sense for the API to reflect this in the data returned. By default, no related models are returned, but they can be requested using the includes query parameter

// request the related 'versions' and 'webhook' models
/my/endpoint?includes=versions,webhooks

Each endpoint has a list of includes you can request. Only request what you need, as the included data can dramatically increase the size of the API response. In some cases, nested relationships or even related model counts can be requested for some endpoints.

Sorting

Core offers sorting functionality on some endpoints to make the results easier to work with. The sort can be specified using a query parameter as follows:

// sort the models by name in descending order
/my/endpoint?sort=-name
// sort the models by name in ascending order
/my/endpoint?sort=name

In some cases, multiple sorts can be applied within the same request:

// sort the models by name in descending order
/my/endpoint?sort=-name
// sort the models by name in ascending order
/my/endpoint?sort=name

Please see individual endpoints for a list of supported sorts.

Pagination

Core offers pagination functionality on some endpoints to make the results easier to work with. The pagination can be specified using a query parameter as follows:

/my/endpoint?page=1&per_page=100

The per_page parameter is optional and will default to a reasonable value for each endpoint. The page parameter is required and must be an integer, starting at 1.