The REST API provides some resources in an additional media type. TheHAL media type application/hal+json describes a format which containslinks and information about other resources. This allows us to embed theprocess definition or assignee of a task directly into the response, which in turnreduces the number of necessary requests to gather all information about asingle task or a list of tasks.

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

{
  "_links" : {},
  "_embedded" : {}
}

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

Request

GET /task/a-task-id

Request Header:

Accept: application/hal+json

Response

{
  "_links" : {
    "self": {
      "href": "/task/a-task-id"
    },
    "assignee": {
      "href": "/user/demo"
    },
    ...
  },
  "_embedded" : {
    "group" : [{
      "_links" : {
        "self" : {
          "href" : "/group/management"
        }
      },
      "_embedded" : null,
      "id" : "management",
      ...
    }],
    "processDefinition" : [ {...}, {...} ],
    ...
  },
  "id" : "a-task-id",
  "name": "Assign Approver",
  "assignee": "demo",
  ...
}

Example: Collection

Request

GET /task

Request Header:

Accept: application/hal+json

Response

{
  "_links" : {
    "self": {
      "href": "/task"
    }
  },
  "_embedded" : {
    "assignee" : [{
      "_links" : {
        "self" : {
          "href" : "/user/demo"
        }
      },
      "_embedded" : null,
      id: "demo",
      ...
    }],
    "processDefinition" : [ {...} ],
    "task" : [{
      "_links" : {
        "self": {
          "href": "/task/a-task-id"
        },
        "assignee": {
          "href": "/user/demo"
        },
        ...
      },
      "_embedded" : {
        "variable" : [ {...}, {...} ]
      },
      "id" : "a-task-id",
      "name": "Assign Approver",
      "assignee": "demo",
      ...
    }, {
      ...
    }]
  },
  "count" : 2
}

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.

This caching can be configured in the web.xml file of the REST API (or the Camunda Web Application incase the REST API is embedded into the Camunda Web Application).

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
  <!-- ... -->
  <listener>
    <listener-class>org.camunda.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
  </listener>
  <context-param>
    <param-name>org.camunda.bpm.engine.rest.hal.cache.config</param-name>
    <param-value>
      {
        "cacheImplementation": "org.camunda.bpm.engine.rest.hal.cache.DefaultHalResourceCache",
        "caches": {
          "org.camunda.bpm.engine.rest.hal.user.HalUser": {
            "capacity": 100,
            "secondsToLive": 900
          },
          "org.camunda.bpm.engine.rest.hal.group.HalGroup": {
            "capacity": 100,
            "secondsToLive": 900
          },
          "org.camunda.bpm.engine.rest.hal.processDefinition.HalProcessDefinition": {
            "capacity": 100,
            "secondsToLive": 600
          }
        }
      }
    </param-value>
  </context-param>
  <!-- ... -->
</web-app>

The HalRelationCacheBootstrap Listener

To bootstrap the caching, the HalRelationCacheBootstrap context listener isused:

<listener>
  <listener-class>org.camunda.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
</listener>

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:

List of Resources Which Support Caching

• 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
• User: org.camunda.bpm.engine.rest.hal.user.HalUser

原文: https://docs.camunda.org/manual/7.9/reference/rest/overview/hal/