Includes

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:

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"
      }
  }
}

​

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.