By default, the Lucca API responds with the JSON representation of the requested resource, nothing more. But you may request for complementary includes, such as:
| Include type | Query | Description |
|---|
| Embedded | ?include=embedded | JSON representations of related resources. For example: the employee the requested leave object belongs to. |
| Links | ?include=links | Links to related resources and/or actions. For example: links to the previous and next pages of a collection. |
| Total count | ?include=totalCount | For collections, the total number of resources that satisfy the query filters across all pages. |
GET /lucca-api/leaves HTTPS/2
?limit=1&include=totalCount,embedded,links
Host: example.ilucca.net
Authorization: Bearer {ACCESS_TOKEN}
Api-Version: {API_VERSION}
Accept: application/json
{
"type": "leaves",
"url": "https://example.ilucca.net/lucca-api/leaves?limit=1&include=embedded,links",
// Total number of items across all pagess
"totalCount": 4362,
"items": [...],
// Includes the representation of related resources.
// Here: the employees the leaves belong to, as well as the leave-accounts of the leaves.
"embedded": {
"employee": {
"id": "416",
"type": "employee",
"url": "https://example.ilucca.net/lucca-api/employees/416",
"givenName": "John",
"familyName": "Doe",
},
"leave-account": {
"12": {
"id": "12",
"type": "leave-account",
"url": "https://example.ilucca.net/lucca-api/leave-account/12",
"name": "Vacations",
"unit": "days"
}
}
},
// Include links to related resources.
// Here, links to the previous and next pages of the collection of leaves
"links": {
"prev": null,
"next": {
"href": "https://example.ilucca.net/lucca-api/leaves?limit=1&page=wjf2&include=totalCount,embedded,links"
}
}
}
You can retrieve multiple types of includes by chaining the query parameter values: ?include=totalCount,embedded,links.
Access rights are evaluated when including embedded resources, thus you may not systematically retrieve them even when including them.
About Embedded
When adding ?include=embedded to your HTTP GET requests, the Lucca API will attempt to include the representations of related resource in the response. For example: you may retrieve the first and last name of the employee when retrieving his leaves.
Notes:
- Embedded resources may not actually be included in responses if you do not have access to them.
- The included representation may be partial, i.e. only give you a subset of the resource properties.
- It may also be stale from cache in the very short term.
- You cannot choose which resources to embed. The list of available resources is dictated by each API endpoint. Including embedded resource is a binary affair: do include them, or do not.
In order to avoid duplicates, embedded resources representations are formatted as a double-level dictionary: indexed by resource type (e.g. leave, employee, etc…) then by id.
About Links
Links are objects that represent navigational references to other resources and/or actions on the target resource. Examples are:
- links to the previous and next pages of a collection.
- link to the approval process of a leave-request.
These can be used to reduce coupling between the client and server implementations, as well as to predict access: the next page link will be null whenever there’s no next page, the link to the approval process will be null whenever the leave-request
is already approved or you have insufficient rights to approve it.
By default, links are omitted from responses, but may be included through the include query parameter. 
