To interact with HAL, you have to set application/hal+json as Accept header. Theresponse of a HAL request always has the following structure:

The property _links contains relational links that give an easy way to navigate betweenassociated resources. A _links property contains at least a self relational link. Theproperty _embedded includes other linked resources in the representing resource. Eachembedded resource will be structured as a HAL resource.

Example: Resource

GET /task/a-task-id

  1. Accept: application/hal+json

Response

Example: Collection

GET /task

Request Header:

  1. Accept: application/hal+json

Response

Caching of HAL Relations

During the generation of a HAL response, linked resources are resolved to embedthem. Some of these resolved resources, like process definitions or users, arerarely modified. Also, if user information is stored in an external system (such asLDAP), every request will access this external system which is anunnecessary overhead. To reduce such expensive requests, the REST API can beconfigured to use a cache to temporary store such relations.

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
  3.   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  4.   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
  6.   <!-- ... -->
  7.   <listener>
  8.     <listener-class>org.camunda.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
  9.   </listener>
  11.   <context-param>
  12.     <param-name>org.camunda.bpm.engine.rest.hal.cache.config</param-name>
  13.     <param-value>
  14.       {
  15.         "cacheImplementation": "org.camunda.bpm.engine.rest.hal.cache.DefaultHalResourceCache",
  16.         "caches": {
  17.           "org.camunda.bpm.engine.rest.hal.user.HalUser": {
  18.             "capacity": 100,
  19.             "secondsToLive": 900
  20.           },
  21.           "org.camunda.bpm.engine.rest.hal.group.HalGroup": {
  23.             "secondsToLive": 900
  24.           "org.camunda.bpm.engine.rest.hal.processDefinition.HalProcessDefinition": {
  25.             "capacity": 100,
  26.             "secondsToLive": 600
  27.           }
  28.         }
  29.       }
  30.     </param-value>
  31.   </context-param>
  33.   <!-- ... -->
  35. </web-app>

To bootstrap the caching, the HalRelationCacheBootstrap context listener isused:

It is configured by the context parameterorg.camunda.bpm.engine.rest.hal.cache.config. The configuration is providedas JSON and consists of two properties:

DefaultHalResourceCache Configuration Options

The simple default cache implementation DefaultHalResourceCache provides following configurationoptions:

Property Description
capacity The number of maximal cache entries.
secondsToLive The number of seconds a cache entry is valid. If a cache entry is expired, it is removed and resolved again.
  • Case Definition: org.camunda.bpm.engine.rest.hal.caseDefinition.HalCaseDefinition
  • Group: org.camunda.bpm.engine.rest.hal.group.HalGroup
  • Identity Links (of a Task): org.camunda.bpm.engine.rest.hal.identitylink.HalIdentityLink
  • Process Definition: org.camunda.bpm.engine.rest.hal.processDefinition.HalProcessDefinition
  • Task: org.camunda.bpm.engine.rest.hal.task.HalTask