Cloudability API

Cloudability API Documentation

Welcome to the Cloudability API documentation.

At Cloudability our public API is a first class citizen. As much as we know you love using our console, a well factored API can deliver and enable myriad use cases beyond even our imagination.
If you are a large public cloud user you'll find intelligent ways to automate scripting of repetitive tasks that would be impractical to manage manually at the scale you require. We also expect to see more machine to machine integrations where information is be shared between systems, augmenting important data sets and supporting the delivery of information to end users in a medium that works for them.

Get Started

Views End Point

Summary

The Views API end point can be used for all key tasks as it pertains to managing Cloudability Views. Cloudability Views allow our customers to give each and every user a unique view or set of views of your cloud spend and usage. It also supports limiting the scope of what is visible to individual users.

  • This endpoint does not support filtering and sorting.

Endpoint Particulars

endpoint: /views for all RESTful CRUD interactions

The Views Object

id (string) - Unique identifier for the Views object.
title (string) - The name of the view as it will appear to end users
sharedWithUsers (array of strings) - The discrete list of users (by their unique identifier) that the view should be shared with
sharedWithOrganization (boolean) - Whether the view should be accessible to the entire organization
ownerId (string) - Unique identifier for the user who created the view
filters (array) - list of filter objects. If multiple filters are applied on the same dimension they are "OR'd", however if they are on different dimensions they are "AND'd". See below regarding filter specifics.

Example Views Object For Valid Views Request

{
  "result": {
    "id": "10000",
    "title": "Vue De Monde",
    "sharedWithOrganization": false,
    "ownerId": "20000",
    "sharedWithUsers": [
      "20000",
      "30000",
      "40000"
    ],
    "filters": [
      {
        "field": "tag1",
        "comparator": "==",
        "value": "Les Bleus"
      }
    ]
  }
}

Special Note About Filters

Views are based on creating filters around Accounts, Account Groups or Tags. You can have multiple filters for any view.

The supported operators are:
!=@, =@, !=, ==, >=, <=, >, <

So for example to create a filter set for your first account group equals 'Production" AND tag number 5 contains 'farm' you'd have:

"filters": [
        {
          "field": "group_name1",
          "comparator": "==",
          "value": "Production"
        },
        {
          "field": "tag5",
          "comparator": "=@",
          "value": "farm"
        }
      ]

Example Requests

Getting List of Views

Quite simply perform a GET request at the /views end point

curl https://api.cloudability.com/v3/views -u '[auth_token]:'

Example Response:

{
  "result": [
    {
      "id": "1000",
      "title": "Fishing Team View",
      "sharedWithOrganization": true,
      "ownerId": "00000",
      "sharedWithUsers": [],
      "filters": [
        {
          "field": "tag5",
          "comparator": "==",
          "value": "fishing"
        }
      ]
    },
    {
      "id": "2000",
      "title": "Farming Team View",
      "sharedWithOrganization": false,
      "ownerId": "00000",
      "sharedWithUsers": [
        "00000",
        "11111"
      ],
      "filters": [
        {
          "field": "tag5",
          "comparator": "==",
          "value": "farming"
        }
      ]
    }
  ]
}  

Create New 'Organization Wide' View

POST your JSON payload to the /views endpoint with the sharedWithOrganization attribute set to true. You should leave the sharedUserIds attribute empty.

curl -X POST https://api.cloudability.com/v3/views \
     -H 'Content-Type: application/json' \
     -u '[auth_token]:' \
     -d @- << EOF
{ 
  "title": "Farmer Team View",
  "sharedWithOrganization": true,
  "sharedWithUsers": [],
  "filters": [{"field":"tag5","comparator":"==","value":"farming"}]
}
EOF

Create New 'User Specific' View

POST your JSON payload to the /views endpoint with your sharedWithUsers attribute containing a list of userIDs the view is to be shared with. The sharedWithOrganization attribute should be set to false.

To get a full list of users and their IDs you can do so currently at our v1 end point. This will be supported on our v3 end point soon.

curl -X POST https://api.cloudability.com/v3/views \
     -H 'Content-Type: application/json' \
     -u '[auth_token]:' \
     -d @- << EOF
{ 
  "title": "Brewer Team View",
  "sharedWithOrganization": false,
  "sharedWithUsers": [
        "00000",
        "11111"
        ],
  "filters": [{"field":"tag5","comparator":"==","value":"brewer"}]
}
EOF

Retrieve Specific View

curl https://api.cloudability.com/v3/views/1000 -u '[auth_token]:'

Update View

PUT your JSON payload to the URI of your specific view resource

curl -X PUT https://api.cloudability.com/v3/views/1000 \
     -H 'Content-Type: application/json' \
     -u '[auth_token]:' \
     -d @- << EOF
{ 
  "title": "Farmer Team View",
  "sharedWithOrganization": true,
  "sharedWithUsers": [],
  "filters": [{"field":"tag5","comparator":"==","value":"farming"}]
}
EOF

Delete View

curl -X DELETE https://api.cloudability.com/v3/views/1000 -u '[auth_token]:'

Archive View

The archive action works differently to the other actions. You'll need to have account ID put into the path as show below. Archiving a credential will delete the vendor link we have but maintain the historical data which has already been collected. This is a good practice when accounts have been decommissioned.

curl -X POST https://api.cloudability.com/v3/vendors/aws/accounts/[account_id]/archive -u '[auth_token]:'

Example Sequence - Add New View; Create New User Defaulted to View

Follow section above to create your view. This will return a view id which you can assign to any user as their default view. You can also get this id from your view list.

Now create a new user (or update a previous one) and include the view id in the default_dimension_filter_set_id attribute

curl -X POST https://app.cloudability.com/api/1/users?auth_token=[auth_token] \
     -H "Content-Type: application/json" \
     -d @- << EOF 
{
  "user": {
    "full_name": "John Doe",
    "role": "User",
    "restricted": false,
    "email": "john_doe@example.com",
    "default_dimension_filter_set_id": [view_id],
    "new_shared_dimension_filter_set_ids": []
  }
}
EOF

As mentioned earlier this is using v1 of our API for user management.

Views End Point