Spectro Cloud platform capabilities are exposed via REST APIs that comply with open API standards.
Every API's URI has the prefix of the version and the Spectro Cloud resource, such as:
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.
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.
|POST||To create a resource or a sub-resource.|
|PUT||To update the resource or a sub-resource. The PUT request will overwrite the existing resource data.|
|PATCH||To add, modify, remove a specific attribute or sub-resource within a resource.|
|DELETE||To delete the resource.|
The API returns standard HTTP response codes:
|200||For a successful response. The response payload will vary depending upon the API. Refer the respective API response schema.|
|201||For a successful resource creation. The response payload contains the uid of the created resource.|
|204||Response without any content for a successful operation. These operations include update, delete and the other actions on the resource.|
|400||Bad request. The request does not adhere to the API request payload schema.|
|401||Missing authorization token or invalid authorization token.|
|403||The API operation is forbidden for the user.|
|404||The resource or the dependent resource is not found for the operation.|
|500||Operational error. For 500 error code, the server responds with an explicit error code and an error message.|
The version information is part of the API URI like
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.
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>
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.