Common Fields

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

• Filters - control which models are returned

• Fields - control the fields returned within each model

• Includes - control the related models returned

• Sorting - control the order of the models returned

• Pagination - control the number of models returned on each page

These are not available on every endpoint, so please check the documentation for the particular 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 the individual endpoint for the list of filters supported.

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 similar to that used for fields:

/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, and 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. It is important to 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 by name descending and age ascending
/my/endpoint?sort=-name,age

Check each endpoint for the list of sorts available.

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.