Count Relations

The count query parameter allows clients to include the count of related resources in the API response. This feature is designed for one-to-many or many-to-many relationships, providing the total number of associated records for specified relations. The count is returned in a {relation_name}_count field for each specified relation.

Usage

The count parameter supports two formats:

Comma-separated list:

?count=relation1,relation2

Array-style query:

?count[]=relation1&count[]=relation2

Response Field

For each specified relation, the API will include a field in the response with the format {relation_name}_count. This field will contain the total number of related records for that relation.

Examples

Single Relation Count

To include the count of a single relation, such as assignments:

GET /api/customer?count=assignments

Response:

{
  "id": 1,
  "name": "Example Customer",
  "assignments_count": 5
}

Multiple Relation Counts

To include the count of multiple relations, such as assignments and contracts:

GET /api/customer?count=assignments,contracts

Response:

{
  "id": 1,
  "name": "Example Customer",
  "assignments_count": 5,
  "contracts_count": 3
}

Array-style Query

You can also specify relations using an array-style query:

GET /api/customer?count[]=assignments&count[]=contracts

This will produce the same result as the comma-separated example above.

Valid Relations

The relations specified in the count parameter must be one-to-many or many-to-many relationships. If a field is not a valid relation or does not meet these criteria, the API will return a 400 Bad Request response with an appropriate error message.

Summary

Use the count parameter to include the count of related resources in API responses.

Specify relations as a comma-separated list or an array-style query.

The count for each relation is returned in a {relation_name}_count field.

By leveraging the count parameter, you can retrieve aggregate information about related resources efficiently, minimizing the need for additional API calls.

Usage#

Response Field#

Examples#

Single Relation Count#

Multiple Relation Counts#

Array-style Query#

Valid Relations#

Summary#