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

Verb	Operation
GET	To List all resources or Get a specific resource. Request Body is not supported
PUT	To Update properties of existing resources. Also used to perform 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 describe 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 requested 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 should 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. Example: 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 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.