The Clumio REST API uses HTTP requests to interact with the Clumio resources, manipulating these resources through JSON-encoded requests and responses. The Clumio REST API architecture strives to follow CRUDL (Create, Read, Update, Delete, List) principles and their mappings to common REST API methods.
The Clumio REST API supports the following REST API methods:
GET
The GET method requests a representation of the specified resource. Requests using GET only retrieve data and never cause a side effect or state change in the server.
For resources that support CRUDL operations, the GET method is used for Read and List operations. For example, send the following GET request to retrieve a list of all registered users.
Request
curl -X GET \
https://us-west-2.api.clumio.com/users \
-H 'Accept: application/api.clumio.*=v1+json' \
-H 'Authorization: Bearer ${BEARER_TOKEN}' \
Response
{
"start": "1",
"total_count": 5,
"total_pages_count": 1,
"current_count": 5,
"limit": 20,
"_links": {
"_self": {
"href": "/users",
"type": "get",
"templated": false
},
"_first": {
"href": "/users?start=1",
"type": "get",
"templated": false
},
... more links
},
"_embedded": {
"items": [
{
"full_name": "Clumian",
"email": "[email protected]",
"is_confirmed": true,
"id": "36",
"is_enabled": true,
"last_activity_timestamp": "2020-04-12T23:20:50Z",
"inviter": "1",
"_links": {
"_self": {
"href": "/users/36",
"type": "get",
"templated": false
},
"update-user": {
"href": "/users/36",
"type": "patch",
"templated": false
},
"delete-user": {
"href": "/users/36",
"type": "delete",
"templated": false
}
},
... Four (4) more items
}
]
}
}
When using GET to perform list operations, you may include query parameters for filtering, sorting, and pagination to better manage the results. For more information about query parameters, go to Filtering, Sorting, and Pagination.
When using GET to perform read operations, use path parameters to point to a specific resource within a collection.
Using the response in the previous example to get the ID for the user named "Clumian" ("id": "36"), set the {user_id} path parameter to 36 in the following request to retrieve data for the user "Clumian":
Endpoint
GET /users/{user_id}
Request
curl -X GET
<https://us-west-2.api.clumio.com/users/36>
-H 'Accept: application/api.clumio.\*=v1+json'
-H 'Authorization: Bearer ${BEARER_TOKEN}' \\
As another example, referring to the following endpoint, send a GET request to return the compliance statistics of AWS EBS volumes protected by policy ID 0e030f9a-7610-40f1-8849-ac022b4e73b7:
Endpoint
GET /policies/definitions/{policy_id}/stats/compliance/aws/ebs-volumes
Request
curl -X GET \
https://us-west-2.api.clumio.com/policies/definitions/0e030f9a-7610-40f1-8849-ac022b4e73b7/stats/compliance/aws/ebs-volumes \
-H 'Accept: application/api.clumio.*=v1+json' \
-H 'Authorization: Bearer ${BEARER_TOKEN}' \
POST
The POST method submits data to the specified resource, often causing a state change in the server.
For resources that support CRUDL operations, the POST method is used to create a new instance of the specified resource. The request body must include all required fields. The response includes the newly created item.
For example, send the following POST /policies/definitions request with its required body parameters name, seed_setting, and slas to create a new backup policy:
Endpoint (with body parameters)
POST /policies/definitions
{
"name": "Just One Backup",
"sla_sets": [
{
"operation": "vmware_vm_backup",
"seed_setting": "immediate",
"slas": [
"rpo_frequency": {
"units": "year",
"value": 1
}
"retention_duration": {
"units": "year",
"value": 1
}
]
}
]
}
Request
curl -X POST \
https://us-west-2.api.clumio.com/policies/definitions \
-H 'Accept: application/api.clumio.*=v1+json' \
-H 'Authorization: Bearer ${BEARER_TOKEN}' \
-d '{
"name": "Just One Backup",
"sla_sets": [
{
"operation": "vmware_vm_backup",
"seed_setting": "immediate",
"slas": [
"rpo_frequency": {
"units": "year",
"value": 1
}
"retention_duration": {
"units": "year",
"value": 1
}
]
}
]
}'
PUT
The PUT method updates the state of a resource.
For resources that support CRUDL operations, the PUT method is used to update a resource by providing an entire replacement object in the request body, and all overwritable fields will be overwritten. The request body for POST and PUT are often similar. The updated resource is returned in the response.
For example, send the following request with the accompanying body parameters to update the policy created above:
Endpoint (with body parameters)
PUT /policies/definitions/da9cd728-e272-436c-9b80-119229260004
{
"name": "Just One Backup Renamed",
"sla_sets": [
{
"operation": "vmware_vm_backup",
"seed_setting": "immediate",
"slas": [
"rpo_frequency": {
"units": "year",
"value": 1
}
"retention_duration": {
"units": "year",
"value": 1
}
]
}
]
}
Request
curl -X PUT \
https://us-west-2.api.clumio.com/policies/definitions/da9cd728-e272-436c-9b80-119229260004 \
-H 'Accept: application/api.clumio.*=v1+json' \
-H 'Authorization: Bearer ${BEARER_TOKEN}' \
-d '{
"name": "Just One Backup Renamed",
"sla_sets": [
{
"operation": "vmware_vm_backup",
"seed_setting": "immediate",
"slas": [
"rpo_frequency": {
"units": "year",
"value": 1
}
"retention_duration": {
"units": "year",
"value": 1
}
]
}
]
}'
PATCH
The PATCH method applies partial modifications to a resource.
For resources that support CRUDL operations, the PATCH method expects a partial object to be provided in the body, and only the fields provided in the PATCH request will be overwritten.
For example, send the following request with the accompanying body parameter full_name to change the name of the user with the user ID 35 to "Clumio Clumian":
Endpoint (with body parameters)
PATCH /users/35
{
"full_name":"Clumio Clumian"
}
Request
curl -X PATCH \
https://us-west-2.api.clumio.com/users/35 \
-H 'Accept: application/api.clumio.*=v1+json' \
-H 'Authorization: Bearer ${BEARER_TOKEN}' \
-d '{
"full_name": "Clumio Clumian"
}'
The response includes a representation of the updated resource.
DELETE
The DELETE method deletes a resource.
For example, send the following request to delete the user with the user ID 35 from the Clumio system:
Endpoint
DELETE /users/35
Request
curl -X DELETE \
https://us-west-2.api.clumio.com/users/35 \
-H 'Accept: application/api.clumio.*=v1+json' \
-H 'Authorization: Bearer ${BEARER_TOKEN}' \
Once an item has been successfully deleted, the server returns an empty body.