Overview

All SaaS CloudCasa REST APIs are rooted at https://api.cloudcasa.io/api/v1. For self hosted CloudCasa installations, the root URL will be https://<CC-SERVER-NAME-OR-IP>/api/v1.
All resources have a “name” field and in most cases, its value must be unique.
Most resources support tags in the form of key-value pairs.
Every created resource will have “_id” field. Do not set this field in the request body while creating a resource.
Some resources also have a “status” field which is used by CloudCasa to describe the current status of the resource. Clients should not set this field in input.
To update resources, use PUT. In a typical use, you would do a GET first, modify some fields, and then do PUT. In this usage, do remember to remove some metadata fields such as “_created”, “_updated”, “_links”, and “_etag” from the request body.

With some updates, you can use PATCH as well.
All requests should set “Content-Type” and “Accept” headers to “application/json”.
Many of the samples and schemas shown may not be exhaustive. In case of any doubts, it is best to do the operation in CloudCasa UI with developer tools enabled. That way, you can see requests and responses of the all the APIs used by the UI.

Authentication

All requests must include “Authorization” header whose value should include API token. Here is an example:

Authorization: Bearer <API-TOKEN>

An API token can be generated from CloudCasa UI. Note that in SaaS, this feature is only available for paid accounts but please feel free to contact us if you are doing a POC and need to explore the API. For selfhosted installations, the feature is always enabled.

Concurrency Control

API responses for every resource include an ETag header and _etag field, which is a hash value representing the current state of the resource on the server. Clients are not allowed to edit (PATCH or PUT) a resource unless they provide an up-to-date ETag for the resource they are attempting to edit. This prevents overwriting items with obsolete versions.

To modify a resource, “If-Match” header must be sent. Here is an example:

If-Match: 00fa3c48c58af86be8222514f2d6452a6a4a6949

If the header is not sent or if invalid value is sent, PATCH and PUT would fail. Here are sample errors:

{
    "_error": {
        "code": 428,
        "message": "To edit a document its etag must be provided using the If-Match header"
    },
    "_status": "ERR"
}

{
    "_error": {
        "code": 412,
        "message": "Client and server etags don't match"
    },
    "_status": "ERR"
}

Filtering

GET responses can be filtered in a very flexible way, using where query parameter. Here are some examples:

List clusters with a given name: /api/v1/kubeclusters?&where={"name":"testcluster"}

List all running copy backup jobs: /v1/jobs?where={"state":"RUNNING","type":"K8S_COPY"}

List all copy jobs that finished with the state “COMPLETED” or “PARTIAL”:

/api/v1/jobs/?where={"state":{"$in":["COMPLETED","PARTIAL"]},"type":"K8S_COPY"}

Sorting

The following API will return entries sorted by the field “_created” in reverse chronological order.

GET /api/v1/jobs?sort=-_created

To sort in chronological order, pass the field without “minus”.

Pagination

By default, GET response can include maximum of 1000 items. This page size can be configured with the query parameters max_results. Maximum allowed value for this parameter is 1000. Similarly, a specific page can be requested using the query parameter page. Example:

GET /api/v1/jobs?max_results=20&page=2

In order to fetch all the resources of a given type, it is ideal to do a GET with some page size, and then check if the response includes a link for next page. Here is a sample response snippet:

"_links": {
     ...
     "next": {
         "href": "v1/kubeclusters?sort=-_created&page=2",
         "title": "next page"
     },
     ...
 }

If “next” link is present, you can do GET again. This can be continued until there is no “next” link in the response.

Pattern matching

You can search fields with string patterns. For example, to return all clusters whose names contain the word “test”

GET /api/v1/kubeclusters?where={"name":{"$regex":".*test.*"}}

To perform case insensitive match, use the following request:

GET /api/v1/kubeclusters?where={"name":{"$regex":"abc.*","$options":"i"}}