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: v1

Before we get to know about the APIs, need to understand some key fundamentals.

CoreStack Organization – Tenant Structure

CoreStack out of the box supports multi-tenancy. In enterprises and IT Organisations, there will be multiple departments and 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 similar mapping,


In an IT organisation, there can be multiple teams such as QA, Engineering, DevOps and these can be considered as tenants in CoreStack. Below diagram shows the similar mapping,


For detailed information about Accounts, Tenants, Users & Roles please refer to 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 loaded now which will show the list of users available under the CoreStack Account
  3. Choose ‘+‘ 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

Steps to regenerate access key & secret key are as follows.

  1. Login in to CoreStack with user having privilege to manage users (eg: 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 loaded now which will show the list of users available under the CoreStack Account
  3. Select the user for whom the API keys are 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

Verb Operation
GET To List all resources or Get a specific resource. Request Body not supported
PUT To Update properties of existing resources. Also used for specific actions on an existing resource.
POST To Create new resource and in some cases used for fetching resources with complex parameters which cannot be accommodated in GET method
DELETE To Delete one or more existing resources

Response Codes

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

Response Code Description
200 – Ok The operation was successful and a response has been returned (GET and PUT requests)
201 – Created The operation was successful, the posted entity has been created and needed information is returned in the response-body (POST request)
204 – No Content The operation was successful, the requested entity has been deleted and therefore there is no response-body returned (DELETE request)
401 – Unauthorized The 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 to be have valid credentials
403 – Forbidden The 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 Found The operation failed. The requested resource was not found.
405 – Method Not Allowed The operation failed. The HTTP method used is not allowed for this resource. E.g. trying to update (PUT) a deployment-resource will result in a 405 status.
409 – Conflict The 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 Error The 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

Type Format
String Plain text parameters. Can contain special characters, numerals and alphabets with proper URL encoding.
Integer Parameter representing an integer value. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647
Long Parameter 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
Boolean Parameter 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
Date Parameter 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

Type Format
String Plain text parameters
Integer Parameter representing an integer value. Can only contain numeric non-decimal values, between -2.147.483.648 and 2.147.483.647
Long Parameter 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
Boolean Parameter 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
Date Parameter 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 used to limit the number of records in the response whereas page in query parameter is to provide page number

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

Actions not supported through API

  • 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 has to 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 requires 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,

Header Value
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