The Clumio REST API implements Hypermedia as the Engine of Application State (HATEOAS) application architecture and JSON Hypermedia API Language (HAL) conventions as the media type format.
HATEOAS enables users to traverse hypermedia links returned in API responses that are most closely associated with the request, eliminating the need for clients to manually specify resource locations (URLs) in their code. Within the HATEOAS implementation, HAL conventions are used to support the programmatic usage of Clumio resources via scripted clients. To learn more about HAL, see the HAL - Hypertext Application Language page.
With the HATEOAS/HAL architecture, API responses contain:
- Links to all possible actions on the resource in its current state.
- Links to all resources that have a relationship with the current resource.
Most responses include a _links field. This field contains links to help the client navigate to other related resources. Examples of _links fields include:
_self, which represents the resource path to the current request_next, which contains the path to the next page of results within List requests, incrementing the start query parameter by one.
It may also include resource-specific links. For example, a policy definition contains links to compliance statistics about entities protected by that policy. See Pagination for more information.
The _embedded property contains a collection of items - known as an array of embedded resources - representing the properties of the resource.
In the following sample response for a GET /tasks request, the _links property displays several links that can be used to navigate to the first, last, or next page of the current request, respectively, while the _embedded property displays the properties of each task, broken down by task ID.
Request
GET /tasks
Response
{
"current_count": 10,
"limit": 10,
"start": "1",
"total_count": 10088,
"total_pages_count": 1009,
"filter_applied": "{\"start_timestamp\":{\"$lte\":"2020-04-12T23:20:50Z"}}",
"_links": {
"_self": {
"href": "/tasks",
"type": "get",
"templated": false
},
"_first": {
"href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=1",
"type": "get",
"templated": false
},
"_last": {
"href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%3A"2020-04-12T23:20:50Z"%7D%7D&start=1009",
"type": "get",
"templated": false
},
"_next": {
"href": "/tasks?filter=%7B%22start_timestamp%22%3A%7B%22%24lte%22%"2020-04-12T23:20:50Z"%7D%7D&start=2",
"type": "get",
"templated": false
}
},
"_embedded": {
"items": [
{
"id": "143717",
"type": "aws_ebs_volume_incremental_backup",
"parent_entity": {
"type": "aws_account_region",
"id": "9c2934fc-ff4d-11e9-8e11-76706df7fe01",
"value": "891106093485/us-west-2"
},
"primary_entity": {
"type": "aws_ebs_volume",
"id": "12e91a96-01e9-11ea-92e9-b68591d87ad1",
"value": "vol-026b0c4326beded57"
},
"status": "completed",
"progress_percentage": 100,
"start_timestamp": "2020-04-12T22:20:50Z",
"end_timestamp": "2020-04-12T22:24:50Z",
"_links": {
"_self": {
"href": "/tasks/143717",
"type": "get",
"templated": false
}
}
},
{
"id": "143587",
"type": "aws_ebs_volume_incremental_backup",
"parent_entity": {
"type": "aws_account_region",
"id": "9c2934fc-ff4d-11e9-8e11-76706df7fe01",
"value": "891106093485/us-west-2"
},
"primary_entity": {
"type": "aws_ebs_volume",
"id": "12e91a96-01e9-11ea-92e9-b68591d87ad1",
"value": "vol-026b0c4326beded57"
},
"status": "completed",
"progress_percentage": 100,
"start_timestamp": "2020-04-11T23:20:50Z",
"end_timestamp": "2020-04-11T23:23:50Z",
"_links": {
"_self": {
"href": "/tasks/143587",
"type": "get",
"templated": false
}
}
},
... plus another 8 other tasks on this page
]
}
}
Embedding Referenced Resources
Certain operations allow you to embed the response of an associated resource. For example, the GET request for an individual alert can include an embedded field to show a representation of its associated consolidated alert. Refer to the resource descriptions in this guide to determine which links are embeddable.
Embedded fields are added to a response by using ?embed=<embeddable_link> as a query parameter, where <embeddable_link> is the operation ID of the embeddable link. This will embed the requested payload in the _embedded field of the response.
For example, the GET /datasources/aws/account-regions endpoint supports the read-account-region-ebs-volumes-compliance-stats embeddable link as a referenced resource to embed compliance statistics about the EBS volumes into each account-region response.
In the request, use the embed query parameter and set it to the read-account-region-ebs-volumes-compliance-stats. For example,
https://us-west-2.api.clumio.com/datasources/aws/environments?embed=read-account-region-ebs-volumes-compliance-stats
In each item of the response, the referenced resource is embedded (_embedded). In the following example, the response embeds read-account-region-ebs-volumes-compliance-stats for each registered AWS Account:
Request
curl -X GET \
'https://us-west-2.api.clumio.com/datasources/aws/environments?embed=read-aws-account-region-ebs-volumes-compliance-stats' \
-H 'Accept: application/api.clumio.*=v1+json' \
-H 'Accept-Encoding: application/api.clumio.*=v1&users=v2+json' \
-H 'Authorization: Bearer ${BEARER_TOKEN}' \
...
Response
{
...
"_embedded": {
"items": [
{
...
},
"_embedded": {
"read-aws-environment-ebs-volumes-compliance-stats": {
"compliant_count": 208,
"non_compliant_count": 1,
"protected_count": 209,
"seeding_in_progress": false,
"unprotected_count": 10
}
}
}
]
}
}
The Clumio REST API versioning and API discovery conventions used along with HATEOAS/HAL standards enable client scripts to evolve independently across resources and versions.