Skip to main content
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 typeQueryDescription
Embedded?include=embeddedJSON representations of related resources. For example: the employee the requested leave object belongs to.
Links?include=linksLinks to related resources and/or actions. For example: links to the previous and next pages of a collection.
Total count?include=totalCountFor 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.
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.