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