Cloud Financial Officer REST API

The REST API exposes 3 resources:

  1. Account - represents information about the accounts being tracked.
  2. Resource - represents an cloud computing asset, like a Server or S3 Bucket.
  3. Report - represents a group of billing records. Each billing record represents a "line item" for a given Resource over a given time.

Account

Accounts are the "top-level" entity exposed by the API. Each Account has a list of its Resources.

RESOURCE LOCATION: /api/v1/accounts/[account-name]

DISCOVERABLE AT: api/v1/accounts OR: api/v1

RESULT FIELDS:

  • id: the name of the account
  • service: the name of the cloud service
  • provider: the name of the cloud service provider
  • url: link to an individual account
  • report_url: link to a report for an individual account
  • resources: an Array of links to an account's Resources
  • billing_codes: an Array of String pairs representing the billing codes for all the resources in this account

Resource

Resources represent individual cloud computing assets, and are always scoped within an Account.

RESOURCE LOCATION: /api/v1/accounts/[account-name]/[resource-type]/[resource-id]

DISCOVERABLE AT: /api/v1/accounts/[account-name]

RESULT FIELDS:

  • resource_id: the cloud provider's ID value for this resource
  • resource_type: "Server", "Volume", "S3 Bucket", etc.
  • account: this resource's account information
  • report_url: link to a report for a specific resource
  • billing_codes: an Array of String pairs representing the billing codes for this resource

Report

Reports are a convenient way of summarizing costs for different combinations of accounts, billing codes, resource types, etc.. In addition to the cost summary, each Report also exposes a list of billing records that make up the total cost of the report. Each billing record describes the costs incurred for one or more Resources over a given duration.

RESOURCE LOCATION: /api/v1/report/[for_[CONSTRAINT]]/[by_[GROUP]]

DISCOVERABLE AT: /api/v1/accounts/[account-name] OR: /api/v1/accounts/[account-name]/[resource-type]/[resource-id]

CONSTRAINT EXPRESSIONS: These limit the scope of the information in the report. Constraints be chained together, irrespective of order.

  • for_account/[account1](/[account2]...)
  • for_resource/[resourceID1](/[resourceID2]...)
  • for_type/[resource_type1](/[resource_type2]...)
  • for_provider/[provider1](/[provider2]...)
  • for_service/[service1](/[service2]...)
  • for_billing_type/[billing_type1](/[billing_type2]...)
  • for_time/[start_datetime]/[stop_datetime]
  • for_code/[key1]/[value1](/[key2]/[value2]...)

GROUPING EXPRESSIONS: These limit the number of records in the report, but not the total cost or duration of the report itself. Each grouping expression causes all records that share the same value for the given grouping attribute to be combined into one record (much like a SQL GROUP_BY clause). Grouping expressions can be chained together, irrespective of order.

  • by_account
  • by_resource
  • by_type
  • by_provider
  • by_service
  • by_billing_type

QUERY PARAMETERS:

  • content-type: text/json or text/csv

REPORT SUMMARY FIELDS:

  • start_time: start time for the earliest billing record in this report
  • stop_time: stop time for the latest billing record in this report
  • total_cost: cost, in cents, for all the billing records in this report
  • cost_per_hour: average hourly cost over all this report's records
  • account: this resource's account information
  • billing_codes: all the billing codes for all this report's records
  • billing_records: Array of billing records that make up this report

Report Generation Details

Each Report represents a set of billing records. At the most granular level, each billing record represents a period of time during which a specific cloud resource incurred charges at a given hourly rate. And if the report was not generated with a by_[GROUP] expression in the URL, then each billing record in the report contains resource-specific data in all the following fields:

BILLING RECORD FIELDS:

  • service: the name of the resource's cloud service
  • provider: the provider for the resource's cloud service
  • account: the name of the resource's account
  • resource_id: the cloud provider's ID value for this resource
  • resource_type: "Server", "Volume", "S3 Bucket", etc
  • billing_type : Some resources, like RDS servers, are billed for both runtime and storage. These costs are distinguished by billing_type.
  • start_time: start time for this billing record
  • stop_time: stop time for this billing record
  • cost_per_hour: hourly cost for this resource over this record's duration
  • total_cost: cost, in cents, for this resource over this record's duration

However, since that level of detail is needed only infrequently, most useful reports group their records by one or more of the fields that make up each record. In this case, all records that share the same value for this grouping field are combined into a "composite record". The values for all the NON-grouping fields in a composite record are set to "*" (which stands for "more than one value") for any fields where the component records don't all share the same value.

Report Generation Examples

[TODO]