Spectro Cloud API

Spectro Cloud platform capabilities are exposed via REST APIs that comply with open API standards.

Paths

Every API's URI has the prefix of the version and the Spectro Cloud resource, such as: v1alpha1/spectroclusters/...

Authentication

All requests must be authenticated with an API token that are passed using the HTTP request header Authorization. Activated users can use the /auth/authenticate API to authenticate and obtain the Authorization token.

Requests

All requests are in the JSON format. In general, the request payload has three sections: metadata, spec and status.

  • metadata consists of common attributes for all the resources such as ids, names, creation timestamps etc.
  • spec consists of attributes that define the resource
  • status contains the status information of the resource. The API does not support creating or modifying the status section.
Certain update request schema have restricted spec resource definition and certain fields like uid, creation timestamp are not allowed to be modified post creation.
HTTP MethodDocumentation
POSTTo create a resource or a sub-resource.
PUTTo update the resource or a sub-resource. The PUT request will overwrite the existing resource data.
PATCHTo add, modify, remove a specific attribute or sub-resource within a resource.
DELETETo delete the resource.

Response Codes

The API returns standard HTTP response codes:

HTTP CodeDescription
200For a successful response. The response payload will vary depending upon the API. Refer the respective API response schema.
201For a successful resource creation. The response payload contains the uid of the created resource.
204Response without any content for a successful operation. These operations include update, delete and the other actions on the resource.
400Bad request. The request does not adhere to the API request payload schema.
401Missing authorization token or invalid authorization token.
403The API operation is forbidden for the user.
404The resource or the dependent resource is not found for the operation.
500Operational error. For 500 error code, the server responds with an explicit error code and an error message.

Versioning

The version information is part of the API URI like v1alpha1, v1. Future APIs will increment the version, leaving the earlier version API intact. The existing API request and response schema will undergo changes like adding new attributes or query params with backward compatibility of earlier schema. While advancing to the next version, ample notice to migrate to the new API will be provided.

Scope

Spectro Cloud applications operate in tenant and project scopes. The resources can be logically grouped as projects and API requests within a project should carry the project uid in the context. The project scope can be specified in the API request as a HTTP header with the key as projectUid and value as the <project uid>

Pagination

The resources list APIs are limited to 50 items and pagination has to be performed to retrieve the complete resources list. The list API response contains listMeta with the continue token. The pagination can be performed based on the presence of the continue token value, and the subsequent request can be performed with the continue token as query param to paginate the rest of the resource items.