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”.

OpenAPI Specification

CloudCasa REST API complies with the OpenAPI Specification (OAS) Version 3. You can obtain the OpenAPI spec by issuing the following API.

GET /api-docs

You can use tools (such as Swagger) to generate documentation and/or client side stubs using the spec returned by CloudCasa.

See also

For general information about OpenAPI, refer to the following official documents:

• “OpenAPI Documentation”

• “OpenAPI Specification v3.1.0”

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 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.

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) or delete (DELETE) 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 or delete 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 DELETE 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"
}

See also

For general information about ETag, refer to the following documents:

• World Wide Web Consortium, The (W3C): Editing the Web: Detecting the Lost Update Problem Using Unreserved Checkout

• MDN Web Docs: ETag:

Filtering

TBD.

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

TBD.

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