HAL links - BlueCat Integrity - 9.5.0

A key constraint of the REST architectural style is HATEOAS or Hypermedia as the Engine of Application State. The v2 RESTful API implements this constraint by embedding a _links object in the JSON representation of resources. These links are used to navigate through Address Manager’s hierarchy of resources, as well as mutate these resources, without having to know the inherent structure of the hierarchy.

The _links object abides by the Hypermedia Application Language or HAL draft IETF standard and is included in JSON representations when the media type application/hal+json or */* is set in the Accept header of the HTTP request. A media type of application/json will exclude the _links field in resource representations.

Note that the _links field is considered metadata and is never a required field in POST or PUT request bodies.

Using HAL links

The example configuration resource below contains links for collections associated with the configuration. To create a view resource for this configuration, a POST request can be made using the views link as the destination resource: _links.views.href (/api/v2/configurations/100881/views in this instance).

Example Configuration resource with HAL links

Request

GET http://{Address_Manager_IP}/api/v2/configurations/100881
Authorization: Basic {basicAuthenticationCredentials}

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "id": 100881,
  "type": "Configuration",
  "name": "config-1",
  "description": null,
  "configurationGroup": null,
  ...
  "_links": {
    "self": {
      "href": "/api/v2/configurations/100881"
    },
    "collection": {
      "href": "/api/v2/configurations"
    },
    "up": {
      "href": "/api/v2/1"
    },
    "accessControlLists": {
      "href": "/api/v2/configurations/100881/accessControlLists"
    },
    "blocks": {
      "href": "/api/v2/configurations/100881/blocks"
    },
    "clientClasses": {
      "href": "/api/v2/configurations/100881/clientClasses"
    },
    "clientIdentifiers": {
      "href": "/api/v2/configurations/100881/clientIdentifiers"
    },
    "deploymentOptions": {
      "href": "/api/v2/configurations/100881/deploymentOptions"
    },
    "deploymentOptionDefinitions": {
      "href": "/api/v2/configurations/100881/deploymentOptionDefinitions"
    },
    "devices": {
      "href": "/api/v2/configurations/100881/devices"
    },
    "macAddresses": {
      "href": "/api/v2/configurations/100881/macAddresses"
    },
    "macPools": {
      "href": "/api/v2/configurations/100881/macPools"
    },
    "merges": {
      "href": "/api/v2/configurations/100881/merges"
    },
    "realms": {
      "href": "/api/v2/configurations/100881/realms"
    },
    "reconciliationPolicies": {
      "href": "/api/v2/configurations/100881/reconciliationPolicies"
    },
    "responsePolicies": {
      "href": "/api/v2/configurations/100881/responsePolicies"
    },
    "servers": {
      "href": "/api/v2/configurations/100881/servers"
    },
    "serverGroups": {
      "href": "/api/v2/configurations/100881/serverGroups"
    },
    "signingKeys": {
      "href": "/api/v2/configurations/100881/signingKeys"
    },
    "splits": {
      "href": "/api/v2/configurations/100881/splits"
    },
    "templates": {
      "href": "/api/v2/configurations/100881/templates"
    },
    "tftpGroups": {
      "href": "/api/v2/configurations/100881/tftpGroups"
    },
    "views": {
      "href": "/api/v2/configurations/100881/views"
    },
    "workflowRequests": {
      "href": "/api/v2/configurations/100881/workflowRequests"
    },
    "zoneGroups": {
      "href": "/api/v2/configurations/100881/zoneGroups"
    },
    "tags": {
      "href": "/api/v2/configurations/100881/tags"
    },
    "accessRights": {
      "href": "/api/v2/configurations/100881/accessRights"
    },
    "transactions": {
      "href": "/api/v2/configurations/100881/transactions"
    }
  }
}