Hypermedia

Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures. With HATEOAS, a client interacts with a network application whose application servers provide information dynamically through hypermedia. A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia. Source

The On Key REST API can generate hypermedia to provide further actions that can be executed for every API response. These links include relevant actions to execute based on the current API flow/context.

Important

As there is overhead in generating hypermedia, hypermedia generation is turned off by default. It can be turned on for the whole system or per tenant via system configuration or alternatively per request by adding the ?includeHypermedia query string parameter

Example

Consider the following excerpts from a sample response that illustrates an array of hypermedia links returned:

{
   "links": [
        {
            "doc": "api/tenants/{client}/{connection}/docs/modules/AOM/resources/Meter/actions/GetMeter",
            "href": "api/tenants/{client}/{connection}/modules/AOM/Meters/1543860691855008",
            "method": "GET",
            "rel": "GetMeter",
            "resource": "Meter",
            "resourceAction": "GetMeter",
            "type": "primaryAction"
        },
        {
            "doc": "api/tenants/{client}/{connection}/docs/modules/AOM/resources/Meter/actions/BatchGetMeter",
            "href": "api/tenants/{client}/{connection}/modules/AOM/Meters/Batch/{ids:IdList}",
            "method": "GET",
            "rel": "BatchGetMeter",
            "resource": "Meter",
            "resourceAction": "BatchGetMeter",
            "type": "primaryAction"
        },
        ...
        {
            "doc": "api/tenants/{client}/{connection}/docs/modules/AOM/resources/Meter/actions/CreateMeter",
            "href": "api/tenants/{client}/{connection}/modules/AOM/Meters/",
            "method": "POST",
            "rel": "CreateMeter",
            "resource": "Meter",
            "resourceAction": "CreateMeter",
            "type": "primaryAction"
        },
        {
            "doc": "api/tenants/{client}/{connection}/docs/modules/AOM/resources/Meter/actions/BatchCreateMeter",
            "href": "api/tenants/{client}/{connection}/modules/AOM/Meters/Batch",
            "method": "POST",
            "rel": "BatchCreateMeter",
            "resource": "Meter",
            "resourceAction": "BatchCreateMeter",
            "type": "primaryAction"
        },
        ...
        {
            "doc": "api/tenants/{client}/{connection}/docs/modules/AOM/resources/MeterReading/actions/GetMeterReadingCollection",
            "href": "api/tenants/{client}/{connection}/modules/AOM/meters/readings/",
            "method": "GET",
            "rel": "GetMeterReadingCollection",
            "resource": "MeterReading",
            "resourceAction": "GetMeterReadingCollection",
            "type": "detail"
        },
        {
            "doc": "api/tenants/{client}/{connection}/docs/modules/AOM/resources/MeterReading/actions/GetMeterReading",
            "href": "api/tenants/{client}/{connection}/modules/AOM/meters/readings/{MeterReading->Id}",
            "method": "GET",
            "rel": "GetMeterReading",
            "resource": "MeterReading",
            "resourceAction": "GetMeterReading",
            "type": "detail"
        },
        ...
        {
            "doc": "api/tenants/{client}/{connection}/docs/modules/AOM/resources/Meter/actions/PauseMeter",
            "href": "api/tenants/{client}/{connection}/modules/AOM/Meters/1543860691855008/Pause",
            "method": "PATCH",
            "rel": "PauseMeter",
            "resource": "Meter",
            "resourceAction": "PauseMeter",
            "type": "customAction"
        },
        {
            "doc": "api/tenants/{client}/{connection}/docs/modules/AOM/resources/Meter/actions/ResumeMeter",
            "href": "api/tenants/{client}/{connection}/modules/AOM/Meters/1543860691855008/Resume",
            "method": "PATCH",
            "rel": "ResumeMeter",
            "resource": "Meter",
            "resourceAction": "ResumeMeter",
            "type": "customAction"
        },
    ]
}

Notice that the list contains different kinds of links like customAction, detail and primaryAction. Based on the current request that was executed, more or less of these contextual links will be available in the response. Use the links provided to provide additional request to execute or to construct an api flow relevant to the process being executed.

Link elements

The elements in the hypermedia link object are:

Element	Required	Description
`href`	Required	The target URL to use in combination with the HTTP `method` to make the related call. `href` is the key HATEOAS component that links a completed call with a subsequent call.
`rel`	Required	The link relationship type or how the `href` link relates to the previous call.
`method`	Required	The HTTP method to use to make a request to the `href` URL.
`doc`	Optional	The documentation URL to use to get more information about the link.
`resource`	Required	The resource associated with the link.
`resourceAction`	Required	The action on the resource associated with the link.
`type`	Optional	The link type that classifies the link with regards to the resource associated with the previous call as follows: `association` - an association with the resource `primaryAction` - a primary action for the resource `customAction` - a custom action for the resource `collection` - a collection associated with the resource `detail` - detail/child resource associated with the resource `lookup` - lookup for the resource `documentation` - documentation for the resource `navigation` - navigation/paging for the resource `specification` - specification for the resource

Table of Contents

Hypermedia

Important

Example

Link elements