Overview

CoreStack offers wide range of REST APIs to integrate with other external services/tools programmatically. With REST API support, it is possible to integrate with almost all of the programming languages while the integration varies from one language to the other.

CoreStack API guide, not only provides the information about the REST APIs available in cURL format, but also provides the code snippets for widely used programming languages in the market such as Java, Python, Javascript, PHP and so on.

Current CoreStack API Version: v3.0

Before we get to know about the APIs, it is important to understand some key fundamentals.

CoreStack Organization – Tenant Structure

CoreStack out of the box supports multi-tenancy. In enterprises and IT organizations, there will be multiple departments. Associates & resources under each department are to be isolated from each other. The isolation is not only needed for financial accounting but also for security and management. Though the associates can have access to multiple departments, but their permissions will vary between departments.

In an enterprise, there can be multiple departments such as Operation, Finance, R&D and these can be considered as tenants in CoreStack. Below diagram shows the sample mapping for a similar setup:

In an IT organization, there can be multiple teams such as QA, Engineering, DevOps and these can be considered as tenants in CoreStack. Below diagram shows the sample mapping for a similar setup:

For detailed information about Accounts, Tenants, Users & Roles, please refer our user guide.

How to get Access Key & Secret Key

In order to access CoreStack APIs, user must have Access Key & Secret Key. Follow the steps provided below to generate Access Key & Secret Key:

1) Login to CoreStack as ops_admin
2) Navigate to Users Page
a. Click the settings icon at the top right
b. Click Users from the menu
C. Users page will be displayed with the list of users available under the CoreStack Account
3) Click ‘+‘ icon to add a new user
4) Fill in the necessary details and provide a valid Email address
5) Select the checkbox “Generate API Access” at the bottom right
6) Click “Create User”
7) The user will receive an email with the API Endpoint, Access Key & Secret Key

Regenerate Access / Secret Keys

Perform the following steps to regenerate access key & secret key:

1) Login in to CoreStack as the user that has the privilege to manage users (e.g., ops_admin)
2) Navigate to Users Page
a. Click the settings icon at the top right
b. Click Users from the menu
c. Users page will be displayed with the list of users available under the CoreStack Account
3) Select the user for whom the API keys need to be regenerated
4) Expand the section “API Access” on the right pane
5) This section will have the Access Key and Valid Till information along with a “REGENERATE KEY” button
6) Clicking on “REGENERATE KEY” button will overwrite the existing key and creates a new key. The old keys will become invalid after regenerating the keys.
7) The user will receive an email with the regenerated Access Key & Secret Key.

HTTP Verbs

Following are the REST API HTTP Verbs supported by CoreStack

VerbOperation
GETTo List all resources or Get a specific resource. Request Body is not supported
PUTTo Update properties of existing resources. Also used to perform specific actions on an existing resource.
POSTTo Create new resource and in some cases used for fetching resources with complex parameters which cannot be accommodated in GET method
DELETETo Delete one or more existing resources

Response Codes

Following are the expected response codes as part of the API response to describe the result of an API operation

Response CodeDescription
200 – OkThe operation was successful and a response has been returned (GET and PUT requests)
201 – CreatedThe operation was successful, the posted entity has been created and requested information is returned in the response-body (POST request)
204 – No ContentThe operation was successful, the requested entity has been deleted and therefore there is no response-body returned (DELETE request)
401 – UnauthorizedThe operation failed. The operation requires Authentication headers to be set. If this was present in the request, there are chances that supplied credentials are not valid or the user is not authorized to perform this operation.
X-Auth-User & X-Auth-Token headers should have valid credentials
403 – ForbiddenThe operation is forbidden and should not be re-attempted. This does not imply an issue with authentication, it’s an operation that is not allowed. Example: deleting a task that is part of a running process is not allowed and will never be allowed, regardless of the user or process/task state
404 – Not FoundThe operation failed. The requested resource was not found.
405 – Method Not AllowedThe operation failed. The HTTP method used is not allowed for this resource. Example: Trying to update (PUT) a deployment-resource will result in a 405 status.
409 – ConflictThe operation failed. The operation causes an update of a resource that has been updated by another operation, which makes the update no longer valid. Can also indicate a resource that is being created in a collection where a resource with that identifier already exists
500 – Internal Server ErrorThe operation failed. An unexpected exception occurred while executing the operation. The response-body contains needed details about the error

Supported Data Types

CoreStack supports widely used data types as part of the URL query parameters and request/response body.

URL Query Parameters

TypeFormat
StringPlain text parameters. Can contain special characters, numerals and alphabets with proper URL encoding.
IntegerParameter representing an integer value. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647
LongParameter representing a long value. Can only contain numeric non-decimal values,
between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807
BooleanParameter representing a Boolean value. Can be either true or false. Any other values other than these two, will be considered as a string input throwing 405 – Bad request response
DateParameter representing a date value. Use the ISO-8601 date-format (see ISO-8601 on wikipedia) with both time and date values (e.g., 2013-04-03T23:45Z)

Request/Response JSON Data Types

TypeFormat
StringPlain text parameters
IntegerParameter representing an integer value. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647
LongParameter representing a long value. Can only contain numeric non-decimal values,
between -9.223.372.036.854.775.808 and 9.223.372.036.854.775.807
BooleanParameter representing a Boolean value. Can be either true or false. Any other values other than these two, will be considered as a string input throwing 405 – Bad request response
DateParameter representing a date value, using a JSON text. Use the ISO-8601 date-format (see ISO-8601 on wikipedia) using both time and date-components (e.g., “2013-04- 03T23:45Z”)

Pagination

Pagination applies to only LIST actions such as ListTenants, ListUsers and so on.

How to?

Limit in query param is used to limit the number of records in the response whereas page in query parameter is used to provide page number

URL: http://<list_api_endpoint>?limit=25&page=2

Actions not supported through API

1) CloudAccount API actions for Azure

Authentication

CoreStack requires Username & Auth token to be passed in all API headers. While username remains constant for a user, Auth token must be generated and provided.

Following API is used to generate Auth Token. All other CoreStack API calls require Username, Auth-token & Tenant ID. Few API calls require Account ID. All these values are available in authentication API response.

Auth token is used for authorization. A CoreStack account can have multiple tenants, hence providing tenant ID is mandatory to perform API operations under the corresponding tenant.

Refer below link for the detailed information about Authentication API

Authentication

Default Headers

Following are the headers expected to be available as part of all API requests.

HeaderValue
Content-Type application/json
X-Auth-User Username
X-Auth-Token Token generated as part of AUTH API

Note: X-Auth-User & X-Auth-Token are required for all API operations except the Authentication API

Example: API execution with Auth Token

The following example demonstrates how to use Authentication headers and retrieve the list of all tenants within a CoreStack Account.

cURL Reference:
curl -X GET -H “X-Auth-Token: [[apiKey]]” -H “X-Auth-User: [[username]]”
URL:  https://cloud.corestack.io/v1/tenants

Sample Request:
curl -X GET -H “X-Auth-Token: abcedefghijklmno34567890” -H “X-Auth-User: cs_user”
URL:  https://cloud.corestack.io/v1/tenants

For more details, click here