CAVE API

The API service exposes all the functionality required to interact with CAVE.

Core Concepts

CAVE has six core concepts, and the REST-ful API is centred around these:

Users

A user is a real-world person who is using CAVE. To become a user, you must sign up for CAVE, using a valid email address. After registration, the user can login to obtain a session token, which can then be used to make API requests.

Operation Description Who can invoke
POST /users/register Begin user registration Anyone
POST /users/confirm Complete user registration Anyone
POST /users/login Begin user session Anyone
POST /users/forgot-password Request password reset Anyone
POST /users/reset-password Confirm password reset Anyone
GET /users/info Retrieve user information Any user
PATCH /users/info Modify user information Any user
GET /users/organizations Retrieve organizations for this user Any user
GET /users/organizations/{name}/teams Retrieve teams for this user Any user

Organizations

An organization is a group of users using CAVE. Any user can create organizations, as long as the name is unique within CAVE. After creating an organization, the user becomes its sole administrator, but there are APIs to allow an administrator to add more users to the organization, remove users from organization, or change the role of an user within the organization.

The supported roles are:

  • Administrator: can do all operations on the organization.
  • Member: can do most operations on the organization.
  • Viewer: can only view data associated with the organization.
Operation Description Who can invoke
POST /organizations Create organization Any user
GET /organizations/{name} Retrieve organization with given name Org Admin or Member
PATCH /organizations/{name} Modify organization with given name Org Admin
DELETE /organizations/{name} Delete organization with given name Org Admin
GET /organizations/{name}/users Retrieve organization users Org Admin
POST /organizations/{name}/users Add user to organization Org Admin
PATCH /organizations/{name}/users/{email} Update role for user in organization Org Admin
DELETE /organizations/{name}/users/{email} Remove user from organization Org Admin

Teams

A team is another level of grouping users within an organization. Any organization administrator can create teams. The only restriction is that the team name must be unique within the organization.

Organization and team administrators can add existing CAVE users to a team, remove users from the team or change the role of a user within the team.

Operation Description Who can invoke
GET /organizations/{name}/teams Retrieve teams for organization Org Admin or Member
POST /organizations/{name}/teams Create team within organization Org Admin
GET /organizations/{name}/teams/{team} Retrieve team by name for organization Team Admin or Member
DELETE /organizations/{name}/teams/{team} Delete team with given name Team Admin
GET /organizations/{name}/teams/{team}/users Retrieve team users Team Admin or Member
POST /organizations/{name}/teams/{team}/users Add user to team Team Admin
PATCH /organizations/{name}/teams/{team}/users/{email} Update role for user in team Team Admin
DELETE /organizations/{name}/teams/{team}/users/{email} Remove user from team Team Admin

Tokens

The tokens are strings that are used to secure requests for writing metrics into CAVE. These can be stored inside applications that are publishing metric data, and are generally known to all members of an organization or team.

A team token can be used to publish metric data for that team. However, organization tokens can be used to publish data for any team, or at the organization level.

The REST API provides operations for token management, and each team will be responsible for their security tokens. It is recommended that the tokens are rotated periodically, for security purposes. There's a limit of 3 tokens per organization, and 3 tokens per team.

Operation Description Who can invoke
GET /organizations/{name}/tokens Get organization tokens Org Admin
POST /organizations/{name}/tokens Create organization token Org Admin
GET /organizations/{name}/tokens/{id} Retrieve organization token with given id Org Admin
DELETE /organizations/{name}/tokens/{id} Delete organization token Org Admin
GET /organizations/{name}/teams/{team}/tokens Get team tokens Team Admin
POST /organizations/{name}/teams/{team}/tokens Create team token Team Admin
GET /organizations/{name}/teams/{team}/tokens/{id} Retrieve team token with given id Team Admin
DELETE /organizations/{name}/teams/{team}/tokens/{id} Delete team token Team Admin

Metrics

Sending metrics to CAVE API is done by POSTing data in JSON format to the metrics endpoint. These requests must be authenticated using valid organization or team tokens, respectively.

Operation Description Who can invoke
POST /organizations/{name}/metrics Publish organization metric data Application using org token
POST /organizations/{name}/teams/{team}/metrics Publish team metric data Application using team token
GET /organizations/{name}/metrics Get organization metric data Org Admin, Member or Viewer
GET /organizations/{name}/teams/{team}/metrics Get team metric data Team Admin, Member or Viewer
GET /organizations/{name}/metric-names List organization metrics Org Admin, Member or Viewer
GET /organizations/{name}/teams/{team}/metric-names List team metrics Team Admin, Member or Viewer

Alerts

Each alert consists of three parts: a condition to be verified, a period of verification, and how to notify the team when the condition is red. In addition, alerts can be enabled or disabled.

Operation Description Who can invoke
GET /organizations/{name}/alerts Retrieve organization alerts for given name Org Admin or Member
POST /organizations/{name}/alerts Create organization alert Org Admin or Member
PATCH /organizations/{name}/alerts/{id} Modify organization alert with given id Org Admin or Member
GET /organizations/{name}/alerts/{id} Retrieve organization alert with given id Org Admin or Member
DELETE /organizations/{name}/alerts/{id} Delete organization alert with given id Org Admin or Member
GET /organizations/{name}/teams/{team}/alerts Retrieve team alerts for given name Team Admin or Member
POST /organizations/{name}/teams/{team}/alerts Create team alert Team Admin or Member
PATCH /organizations/{name}/teams/{team}/alerts/{id} Modify team alert with given id Team Admin or Member
GET /organizations/{name}/teams/{team}/alerts/{id} Retrieve team alert with given id Team Admin or Member
DELETE /organizations/{name}/teams/{team}/alerts/{id} Delete team alert with given id Team Admin or Member