Getting started with Cloudability API V3

API Authentication

curl https://api.cloudability.com/v3/budgets -u 'Your_API_Key:'

API Interactions

curl https://api.cloudability.com/v3/budgets -u 'Your_API_Key:'

curl https://api.cloudability.com/v3/budgets -H "apptio-opentoken: [apptio opentoken]" -H "apptio-environmentid: [apptio Access Administration environment id]"

Response Format

All successful responses will be in the following format:

{
    result: {} or [],
    meta: {},
}

• result will contain the results or payload for the call.

• Ancillary information (such as pagination breakdowns and others) will exist in the meta attribute, if relevant.

• Primitive values will be null if no value is present (that is, numbers, strings).

• Objects and arrays will return their empty states ( [] ) if no value is present.

• Dates are represented in ISO 8601 standard and use the YYYY-MM-DD format.

Headers

POST and PUT requests

Content-Type: application/json

GET requests (for all end points)

Accept: application/json

GET requests (supported by some end points)

Accept: text/csv

Authorization (if using Cloudability API keys)

Authorization: Basic <cldy_token>

Pagination

Not all end points support pagination. The end points that do not support pagination will always return all records. The end points that support pagination will return the first 50 matching records by default.

When attempting pagination, you must use the limit and offset parameters together. When you use these parameters, the result set will be restricted to the specified limit from the offset value.

The default value for limit is 50 (returns 50 records) and offset is 0 (start of the records).

Example

The following example shows how to use the limit and offset parameters with sort .

/views?limit=5&offset=20

Sorting

Use the sort query parameter sort your results. To specify the sort order, you can add - (descending) or + (ascending) before the attribute.

Examples

Sort the results for the portfolio end point by the end attribute in descending order.

/portfolio/ec2?sort=-end

Sort the results for the portfolio end point by the end attribute in ascending order.

/portfolio/ec2?sort=%2bend

(Make sure to correctly encode the + symbol.)

Filtering

When you use the filter query parameter, you supply a dimension you want to filter on, followed by the filter expression.

Filtered queries restrict the rows that are included in the result. Only the rows that meet the filter conditions are included in the result. Note that the client libraries automatically URL encode the filter operators. However, if you make requests directly to the protocol, you must explicitly URL encode the following filter operators. Also, filtering occurs before any dimensions are aggregated so that the returned metrics represent the total for only the relevant records.

Filter syntax: name operator expression

name: The name of the dimension on which to filter.

operator: Specifies the type of filter match to use. You can use the following operators:

== (equals)

!= (does not equal)

> (greater than)

< (less than)

>= (greater than or equal to)

<= (less than or equal to)

=@ (contains)

!=@ (does not contain)

expression: States the values included in the results.

To apply multiple filters to a request, delimit with commas in one filter parameter.

Examples

Check if the state is active:

/portfolio/ec2?filter=state==active

Check if the state is retired:

/portfolio/ec2?filter=state==retired

Check if the end is less than 1541803776000:

/portfolio/ec2?filter=end<1541803776000

Check if the end is greater than 1541803776000:

/portfolio/ec2?filter=end>1541803776000

Apply multiple filters:

/portfolio/ec2?filter=state==active,end>1541803776000

Cloudability end point examples

The documentation for each end point will include a number of examples which will show how to interact with the API. The examples will use cURL for HTTP interactions and jq for parsing JSON. Both of these CLI tools are widely used and can be easily employed to interact with a RESTful API.