# 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:

<table><thead><tr><th width="276.12890625">Common functionality</th><th>Controls...</th></tr></thead><tbody><tr><td><a href="#filters">Filters</a></td><td>Which models are returned.</td></tr><tr><td><a href="#fields">Fields</a></td><td>The fields returned within each model.</td></tr><tr><td><a href="#includes">Includes</a></td><td>The related models returned.</td></tr><tr><td><a href="#sorting">Sorting</a></td><td>The order of the models returned.</td></tr><tr><td><a href="#pagination">Pagination</a></td><td>The number of models returned on each page</td></tr></tbody></table>

{% hint style="info" %}
These are not available in all cases; please check the documentation for the specific endpoint needed.
{% endhint %}

## 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:

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

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:

{% code lineNumbers="true" %}

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

{% endcode %}

{% hint style="info" %}
Most endpoints do not allow this functionality, but it is becoming more widely available over time.
{% endhint %}

## 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

{% code lineNumbers="true" %}

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

{% endcode %}

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:

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

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:

{% code lineNumbers="true" %}

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

{% endcode %}

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.