Skip to content

Latest commit

 

History

History
2445 lines (2333 loc) · 64.6 KB

api.md

File metadata and controls

2445 lines (2333 loc) · 64.6 KB

Abacus Metering and Aggregation REST API

The Abacus Usage Metering and Aggregation REST API can be used by Cloud resource providers to submit usage data, usage dashboards to retrieve real time usage reports, and billing systems to retrieve the aggregated and rated usage data needed for billing. Cloud resources include services and application runtimes or containers for example.

Usage data is exchanged with Abacus in the form of usage documents. Each document type has a JSON representation and one or more REST methods.

Document types

Resource usage collection

Resource configuration

Resource pricing

Usage summary report

GraphQL usage query

Resource usage

The resource usage collection API can be used by Cloud resource providers to submit usage for instances of Cloud resources, including service instances and application runtimes or containers.

Usage can be submitted by POSTing resource usage documents to Abacus.

A resource usage document contains usage measurements for a Cloud resource.

Once a resource usage document has been submitted to Abacus it can be retrieved using GET.

Method: insert

HTTP request:

POST /v1/metering/collected/usage with a resource usage document

Description: Records the resource usage document and processes the Cloud resource usage data it contains.

HTTP response: 201 to indicate success with the URL of the resource usage document in a Location header, 400 to report an invalid request, 500 to report a server error.

Method: get

HTTP request:

GET /v1/metering/collected/usage/:usage_document_id

Description: Retrieves a previously submitted resource usage document.

HTTP response: 200 to indicate success with the requested resource usage document, 404 if the usage is not found, 500 to report a server error.

JSON representation:

{
  "start": 1396421450000,
  "end": 1396421451000,
  "organization_id": "us-south:54257f98-83f0-4eca-ae04-9ea35277a538",
  "space_id": "d98b5916-3c77-44b9-ac12-04456df23eae",
  "consumer_id": "app:d98b5916-3c77-44b9-ac12-045678edabae",
  "resource_id": "object-storage",
  "plan_id": "basic",
  "resource_instance_id": "d98b5916-3c77-44b9-ac12-04d61c7a4eae",
  "measured_usage": [
    {
      "measure": "storage",
      "quantity": 10
    },
    {
      "measure": "api_calls",
      "quantity": 10
    }
  ]
}

JSON schema:

{
  "type": "object",
  "required": [
    "usage"
  ],
  "properties": {
    "start": {
      "type": "integer",
      "format": "utc-millisec"
    },
    "end": {
      "type": "integer",
      "format": "utc-millisec"
    },
    "organization_id": {
      "type": "string"
    },
    "space_id": {
      "type": "string"
    },
    "consumer_id": {
      "type": "string"
    },
    "resource_id": {
      "type": "string"
    },
    "plan_id": {
      "type": "string"
    },
    "resource_instance_id": {
      "type": "string"
    },
    "measured_usage": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "measure",
          "quantity"
        ],
        "properties": {
          "measure": {
            "type": "string"
          },
          "quantity": {
            "type": "number"
          }
        },
        "additionalProperties": false
      },
      "additionalItems": false
    }
  },
  "additionalProperties": false,
  "title": "Resource Usage"
}

Resource type

The resource type API is used by abacus to retrieve resource type for Cloud resources.

This API enable Cloud platform integrating Abacus to generalizes onboarded resource_ids to a single resource type.

Method: get

HTTP request:

GET /v1/provisioning/resources/:resource_id/type

Description: Retrieves the resource type for the specified resource id.

HTTP response: 200 to indicate success with the requested resource type, 404 if the resource type is not found, 500 to report a server error.

Metering plan id

The metering plan id API is used by abacus to retrieve metering plan id for Cloud resources.

Given the organization id, resource type, plan id, and time returns the metering plan id.

This API gives more flexibility to Cloud platform integrating Abacus. Cloud platform integrating Abacus would be able give different way of metering depending on the given organization id, resource type, plan id, and time.

Method: get

HTTP request:

GET /v1/metering/organizations/:organization_id/resource_types/:resource_type/plans/:plan_id/time/:time/metering_plan/id

Description: Retrieves the metering plan of the specified organization id, resource type, plan id at the specified time.

HTTP response: 200 to indicate success with the requested metering plan id, 404 if the metering plan id is not found, 500 to report a server error.

Rating plan id

The rating plan id API is used by abacus to retrieve rating plan id for Cloud resources.

Given the organization id, resource type, plan id, and time returns the rating plan id.

This API gives more flexibility to Cloud platform integrating Abacus. Cloud platform integrating Abacus would be able give different way of rating depending on the given organization id, resource type, plan id, and time.

Method: get

HTTP request:

GET /v1/rating/organizations/:organization_id/resource_types/:resource_type/plans/:plan_id/time/:time/rating_plan/id

Description: Retrieves the rating plan of the specified organization id, resource type, plan id at the specified time.

HTTP response: 200 to indicate success with the requested rating plan id, 404 if the rating plan id is not found, 500 to report a server error.

Pricing plan id

The pricing plan id API is used by abacus to retrieve pricing plan id for Cloud resources.

Given the organization id, resource type, plan id, and time returns the pricing plan id.

This API gives more flexibility to Cloud platform integrating Abacus. Cloud platform integrating Abacus would be able give different pricing depending on the given organization id, resource type, plan id, and time.

Method: get

HTTP request:

GET /v1/pricing/organizations/:organization_id/resource_types/:resource_type/plans/:plan_id/time/:time/pricing_plan/id

Description: Retrieves the pricing plan of the specified organization id, resource type, plan id at the specified time.

HTTP response: 200 to indicate success with the requested pricing plan id, 404 if the pricing plan id is not found, 500 to report a server error.

Metering plans

The metering plans API is used by Abacus to retrieve metering plan documents for Cloud resources.

Metering plan documents describe the types of measurements, metrics, units, and metering, accumulation, aggregation, and reporting formulas that must be used by Abacus to meter, and report usage for each type of Cloud resource.

This API defines the contract between Abacus and the Cloud platform integrating it. The Cloud platform can manage and store metering plan documents describing its Cloud resources in a platform specific way outside of Abacus, and is simply expected to make these documents available to Abacus at an API endpoint supporting a GET method.

Method: get

HTTP request:

GET /v1/metering/plans/:metering_plan_id

Description: Retrieves the metering plan of the specified metering plan id.

HTTP response: 200 to indicate success with the requested metering configuration document, 404 if the configuration is not found, 500 to report a server error.

JSON representation:

{
  "plan_id": "basic-object-storage",
  "measures": [
    {
      "name": "storage",
      "unit": "BYTE"
    },
    {
      "name": "api_calls",
      "units": "CALL"
    }
  ],
  "metrics": [
    {
      "name": "storage",
      "unit": "GIGABYTE",
      "meter": "(m) => m.storage / 1073741824",
      "accumulate": "(a, qty) => Math.max(a, qty)"
    },
    {
      "name": "thousand_api_calls",
      "unit": "THOUSAND_CALLS",
      "meter": "(m) => m.light_api_calls / 1000",
      "accumulate": "(a, qty) => a ? a + qty : qty",
      "aggregate": "(a, qty) => a ? a + qty : qty",
      "summarize": "(t, qty) => qty"
    }
  ]
}

JSON schema:

{
  "type": "object",
  "required": [
    "plan_id",
    "measures",
    "metrics"
  ],
  "properties": {
    "plan_id": {
      "type": "string"
    },
    "measures": {
      "type": "array",
      "minItems": "1",
      "items": {
        "type": "object",
        "required": [
          "name",
          "unit"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "additionalItems": false
    },
    "metrics": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "name",
          "unit"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "meter": {
            "type": "string"
          },
          "accumulate": {
            "type": "string"
          },
          "aggregate": {
            "type": "string"
          },
          "summarize": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "additionalItems": false
    },
  "additionalProperties": false,
  "title": "Metering Plan"
}

Rating plans

The rating plans API is used by Abacus to retrieve rating plan documents for Cloud resources.

Rating plan documents describe the types of metrics, and rating, and charge formulas that must be used by Abacus to rate, and report usage for each type of Cloud resource.

This API defines the contract between Abacus and the Cloud platform integrating it. The Cloud platform can manage and store rating plan documents describing its Cloud resources in a platform specific way outside of Abacus, and is simply expected to make these documents available to Abacus at an API endpoint supporting a GET method.

Method: get

HTTP request:

GET /v1/rating/plans/:rating_plan_id

Description: Retrieves the rating plan of the specified rating plan id.

HTTP response: 200 to indicate success with the requested rating plan document, 404 if the plan is not found, 500 to report a server error.

JSON representation:

{
  "plan_id": "object-rating-plan",
  "metrics": [
    {
      "name": "storage"
    },
    {
      "name": "thousand_api_calls",
      "rate": "(p, qty) => p ? p * qty : 0",
      "charge": "(t, cost) => cost"
    }
  ]
}

JSON schema:

{
  "type": "object",
  "required": [
    "plan_id",
    "metrics"
  ],
  "properties": {
    "plan_id": {
      "type": "string"
    },
    "metrics": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "rate": {
            "type": "string"
          },
          "charge": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "additionalItems": false
    },
  "additionalProperties": false,
  "title": "Metering Plan"
}

Pricing plans

The pricing plans API is used by Abacus to retrieve pricing plan data for Cloud resources.

Pricing plan documents are used to configure the prices of the metrics used to rate Cloud resources. Different prices can be defined for different countries.

This API defines the contract between Abacus and the Cloud platform integrating it. The Cloud platform can manage and store pricing plan data for its Cloud resources in a platform specific way outside of Abacus, and is simply expected to make the pricing data available to Abacus at an API endpoint supporting a GET method.

Method: get

HTTP request:

GET /v1/pricing/plans/:pricing_plan_id

Description: Retrieves the pricing of the specified pricing plan id.

HTTP response: 200 to indicate success with the requested pricing plan data, 404 if the pricing data is not found, 500 to report a server error.

JSON representation:

{
  "plan_id": "object-pricing-basic",
  "metrics": [
    {
      "name": "storage",
      "prices": [
        {
          "country": "USA",
          "price": 1
        },
        {
          "country": "EUR",
          "price": 0.7523
        },
        {
          "country": "CAN",
          "price": 1.06
        }
      ]
    },
    {
      "name": "thousand_api_calls",
      "prices": [
        {
          "country": "USA",
          "price": 0.03
        },
        {
          "country": "EUR",
          "price": 0.0226
        },
        {
          "country": "CAN",
          "price": 0.0317
        }
      ]
    }
  ]
}

JSON schema:

{
  "title": "Price Plan",
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "string"
    },
    "metrics": {
      "type": "array",
      "minItems": 1,
      "items": {
        "title": "metric",
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "prices": {
            "type": "array",
            "minItems": 1,
            "items": {
              "title": "price",
              "type": "object",
              "properties": {
                "country": {
                  "type": "string"
                },
                "price": {
                  "type": "number"
                }
              },
              "required": [
                "country",
                "price"
              ],
              "additionalProperties": false
            },
            "additionalItems": false
          }
        },
        "required": [
          "name",
          "prices"
        ],
        "additionalProperties": false
      },
      "additionalItems": false
    }
  },
  "required": [
    "plan_id",
    "metrics"
  ],
  "additionalProperties": false
}

Usage summary report

The usage summary report API can be used to retrieve aggregated usage summary report documents from Abacus.

Method: get

HTTP request:

GET /v1/metering/organizations/:organization_id/aggregated/usage/:time

Description: Retrieves a usage report document containing a summary of the aggregated Cloud resource usage incurred by the specified organization at the specified time.

HTTP response: 200 to indicate success with a usage summary report JSON document, 404 if the usage is not found, 500 to report a server error.

JSON representation:

{
  "start": 1435622400000,
  "end": 1435708799999,
  "processed": 1435708800000,
  "organization_id": "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
  "windows": [
    [{
      "charge": 46.09,
    }],
    [{
      "charge": 46.09,
    }],
    [{
      "charge": 46.09,
    }],
    [{
      "charge": 46.09,
    }],
    [{
      "charge": 46.09,
    }]
  ],
  "id": "k-a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27-t-0001435622400000",
  "spaces": [
    {
      "space_id": "aaeae239-f3f8-483c-9dd0-de5d41c38b6a",
      "windows": [
        [{
          "charge": 46.09,
        }],
        [{
          "charge": 46.09,
        }],
        [{
          "charge": 46.09,
        }],
        [{
          "charge": 46.09,
        }],
        [{
          "charge": 46.09,
        }]
      ],
      "consumers": [
        {
          "consumer_id": "app:d98b5916-3c77-44b9-ac12-045678edabae",
          "windows": [
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }]
          ],
          "resources": [
            {
              "resource_id": "object-storage",
              "charge": 46.09,
              "aggregated_usage": [
                {
                  "metric": "storage",
                  "windows": [
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }],
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }],
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }],
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }],
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }]
                  ]
                },
                {
                  "metric": "thousand_light_api_calls",
                  "windows": [
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }],
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }],
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }],
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }],
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }]
                  ]
                },
                {
                  "metric": "heavy_api_calls",
                  "windows": [
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }],
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }],
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }],
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }],
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }]
                  ]
                }
              ],
              "plans": [
                {
                  "plan_id": "basic",
                  "windows": [
                    [{
                      "charge": 46.09,
                    }],
                    [{
                      "charge": 46.09,
                    }],
                    [{
                      "charge": 46.09,
                    }],
                    [{
                      "charge": 46.09,
                    }],
                    [{
                      "charge": 46.09,
                    }]
                  ],
                  "aggregated_usage": [
                    {
                      "metric": "storage",
                      "windows": [
                        [{
                          "quantity": 1,
                          "summary": 1,
                          "cost": 1,
                          "charge": 1
                        }],
                        [{
                          "quantity": 1,
                          "summary": 1,
                          "cost": 1,
                          "charge": 1
                        }],
                        [{
                          "quantity": 1,
                          "summary": 1,
                          "cost": 1,
                          "charge": 1
                        }],
                        [{
                          "quantity": 1,
                          "summary": 1,
                          "cost": 1,
                          "charge": 1
                        }],
                        [{
                          "quantity": 1,
                          "summary": 1,
                          "cost": 1,
                          "charge": 1
                        }]
                      ]
                    },
                    {
                      "metric": "thousand_light_api_calls",
                      "windows": [
                        [{
                          "quantity": 3,
                          "summary": 3,
                          "cost": 0.09,
                          "charge": 0.09
                        }],
                        [{
                          "quantity": 3,
                          "summary": 3,
                          "cost": 0.09,
                          "charge": 0.09
                        }],
                        [{
                          "quantity": 3,
                          "summary": 3,
                          "cost": 0.09,
                          "charge": 0.09
                        }],
                        [{
                          "quantity": 3,
                          "summary": 3,
                          "cost": 0.09,
                          "charge": 0.09
                        }],
                        [{
                          "quantity": 3,
                          "summary": 3,
                          "cost": 0.09,
                          "charge": 0.09
                        }]
                      ]
                    },
                    {
                      "metric": "heavy_api_calls",
                      "windows": [
                        [{
                          "quantity": 300,
                          "summary": 300,
                          "cost": 45,
                          "charge": 45
                        }],
                        [{
                          "quantity": 300,
                          "summary": 300,
                          "cost": 45,
                          "charge": 45
                        }],
                        [{
                          "quantity": 300,
                          "summary": 300,
                          "cost": 45,
                          "charge": 45
                        }],
                        [{
                          "quantity": 300,
                          "summary": 300,
                          "cost": 45,
                          "charge": 45
                        }],
                        [{
                          "quantity": 300,
                          "summary": 300,
                          "cost": 45,
                          "charge": 45
                        }]
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "resources": [
        {
          "resource_id": "object-storage",
          "windows": [
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }]
          ],
          "aggregated_usage": [
            {
              "metric": "storage",
              "windows": [
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }],
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }],
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }],
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }],
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }]
              ]
            },
            {
              "metric": "thousand_light_api_calls",
              "windows": [
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }],
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }],
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }],
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }],
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }]
              ]
            },
            {
              "metric": "heavy_api_calls",
              "windows": [
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }],
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }],
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }],
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }],
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }]
              ]
            }
          ],
          "plans": [
            {
              "plan_id": "basic",
              "windows": [
                [{
                  "charge": 46.09,
                }],
                [{
                  "charge": 46.09,
                }],
                [{
                  "charge": 46.09,
                }],
                [{
                  "charge": 46.09,
                }],
                [{
                  "charge": 46.09,
                }]
              ],
              "aggregated_usage": [
                {
                  "metric": "storage",
                  "windows": [
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }],
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }],
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }],
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }],
                    [{
                      "quantity": 1,
                      "summary": 1,
                      "charge": 1
                    }]
                  ]
                },
                {
                  "metric": "thousand_light_api_calls",
                  "windows": [
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }],
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }],
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }],
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }],
                    [{
                      "quantity": 3,
                      "summary": 3,
                      "charge": 0.09
                    }]
                  ]
                },
                {
                  "metric": "heavy_api_calls",
                  "windows": [
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }],
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }],
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }],
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }],
                    [{
                      "quantity": 300,
                      "summary": 300,
                      "charge": 45
                    }]
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "resources": [
    {
      "resource_id": "object-storage",
      "windows": [
        [{
          "charge": 46.09,
        }],
        [{
          "charge": 46.09,
        }],
        [{
          "charge": 46.09,
        }],
        [{
          "charge": 46.09,
        }],
        [{
          "charge": 46.09,
        }]
      ],
      "aggregated_usage": [
        {
          "metric": "storage",
          "windows": [
            [{
              "quantity": 1,
              "summary": 1,
              "charge": 1
            }],
            [{
              "quantity": 1,
              "summary": 1,
              "charge": 1
            }],
            [{
              "quantity": 1,
              "summary": 1,
              "charge": 1
            }],
            [{
              "quantity": 1,
              "summary": 1,
              "charge": 1
            }],
            [{
              "quantity": 1,
              "summary": 1,
              "charge": 1
            }]
          ]
        },
        {
          "metric": "thousand_light_api_calls",
          "windows": [
            [{
              "quantity": 3,
              "summary": 3,
              "charge": 0.09
            }],
            [{
              "quantity": 3,
              "summary": 3,
              "charge": 0.09
            }],
            [{
              "quantity": 3,
              "summary": 3,
              "charge": 0.09
            }],
            [{
              "quantity": 3,
              "summary": 3,
              "charge": 0.09
            }],
            [{
              "quantity": 3,
              "summary": 3,
              "charge": 0.09
            }]
          ]
        },
        {
          "metric": "heavy_api_calls",
          "windows": [
            [{
              "quantity": 300,
              "summary": 300,
              "charge": 45
            }],
            [{
              "quantity": 300,
              "summary": 300,
              "charge": 45
            }],
            [{
              "quantity": 300,
              "summary": 300,
              "charge": 45
            }],
            [{
              "quantity": 300,
              "summary": 300,
              "charge": 45
            }],
            [{
              "quantity": 300,
              "summary": 300,
              "charge": 45
            }]
          ]
        }
      ],
      "plans": [
        {
          "plan_id": "basic",
          "windows": [
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }],
            [{
              "charge": 46.09,
            }]
          ],
          "aggregated_usage": [
            {
              "metric": "storage",
              "windows": [
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }],
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }],
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }],
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }],
                [{
                  "quantity": 1,
                  "summary": 1,
                  "charge": 1
                }]
              ]
            },
            {
              "metric": "thousand_light_api_calls",
              "windows": [
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }],
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }],
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }],
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }],
                [{
                  "quantity": 3,
                  "summary": 3,
                  "charge": 0.09
                }]
              ]
            },
            {
              "metric": "heavy_api_calls",
              "windows": [
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }],
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }],
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }],
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }],
                [{
                  "quantity": 300,
                  "summary": 300,
                  "charge": 45
                }]
              ]
            }
          ]
        }
      ]
    }
  ]
}

JSON schema:

{
  "title": "organizationReport",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "start": {
      "type": "integer",
      "format": "utc-millisec"
    },
    "end": {
      "type": "integer",
      "format": "utc-millisec"
    },
    "processed": {
      "type": "integer",
      "format": "utc-millisec"
    },
    "organization_id": {
      "type": "string"
    },
    "windows": {
      "type": "array",
      "items": {
        "title": "cwindow",
        "type": "object",
        "properties": {
          "charge": {
            "type": "number"
          }
        },
        "required": [
          "charge"
        ]
      }
    },
    "resources": {
      "type": "array",
      "minItems": 1,
      "items": {
        "title": "resource",
        "type": "object",
        "properties": {
          "resource_id": {
            "type": "string"
          },
          "windows": {
            "type": "array",
            "items": {
              "title": "cwindow",
              "type": "object",
              "properties": {
                "charge": {
                  "type": "number"
                }
              },
              "required": [
                "charge"
              ]
            }
          },
          "aggregated_usage": {
            "type": "array",
            "minItems": 1,
            "items": {
              "title": "rmetric",
              "type": "object",
              "properties": {
                "metric": {
                  "type": "string"
                },
                "windows": {
                  "type": "array",
                  "items": {
                    "title": "rwindow",
                    "type": "object",
                    "properties": {
                      "quantity": {
                        "type": "number"
                      },
                      "summary": {
                        "type": "number"
                      },
                      "charge": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "quantity",
                      "summary",
                      "charge"
                    ]
                  }
                }
              },
              "required": [
                "metric",
                "windows"
              ],
              "additionalProperties": false
            },
            "additionalItems": false
          },
          "plans": {
            "type": "array",
            "minItems": 1,
            "items": {
              "title": "plan",
              "type": "object",
              "properties": {
                "plan_id": {
                  "type": "string"
                },
                "windows": {
                  "type": "array",
                  "items": {
                    "title": "cwindow",
                    "type": "object",
                    "properties": {
                      "charge": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "charge"
                    ]
                  }
                },
                "aggregated_usage": {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "title": "pmetric",
                    "type": "object",
                    "properties": {
                      "metric": {
                        "type": "string"
                      },
                      "windows": {
                        "type": "array",
                        "items": {
                          "title": "pwindow",
                          "type": "object",
                          "properties": {
                            "quantity": {
                              "type": "number"
                            },
                            "summary": {
                              "type": "number"
                            },
                            "cost": {
                              "type": "number"
                            },
                            "charge": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "quantity",
                            "summary",
                            "cost",
                            "charge"
                          ]
                        }
                      }
                    },
                    "required": [
                      "metric",
                      "windows"
                    ],
                    "additionalProperties": false
                  },
                  "additionalItems": false
                }
              },
              "required": [
                "plan_id",
                "windows",
                "aggregated_usage"
              ],
              "additionalProperties": false
            },
            "additionalItems": false
          }
        },
        "required": [
          "resource_id",
          "windows",
          "aggregated_usage",
          "plans"
        ],
        "additionalProperties": false
      },
      "additionalItems": false
    },
    "spaces": {
      "type": "array",
      "minItems": 1,
      "items": {
        "title": "space",
        "type": "object",
        "properties": {
          "space_id": {
            "type": "string"
          },
          "windows": {
            "type": "array",
            "items": {
              "title": "cwindow",
              "type": "object",
              "properties": {
                "charge": {
                  "type": "number"
                }
              },
              "required": [
                "charge"
              ]
            }
          },
          "resources": {
            "type": "array",
            "minItems": 1,
            "items": {
              "title": "resource",
              "type": "object",
              "properties": {
                "resource_id": {
                  "type": "string"
                },
                "windows": {
                  "type": "array",
                  "items": {
                    "title": "cwindow",
                    "type": "object",
                    "properties": {
                      "charge": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "charge"
                    ]
                  }
                },
                "aggregated_usage": {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "title": "rmetric",
                    "type": "object",
                    "properties": {
                      "metric": {
                        "type": "string"
                      },
                      "windows": {
                        "type": "array",
                        "items": {
                          "title": "rwindow",
                          "type": "object",
                          "properties": {
                            "quantity": {
                              "type": "number"
                            },
                            "summary": {
                              "type": "number"
                            },
                            "charge": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "quantity",
                            "summary",
                            "charge"
                          ]
                        }
                      }
                    },
                    "required": [
                      "metric",
                      "windows"
                    ],
                    "additionalProperties": false
                  },
                  "additionalItems": false
                },
                "plans": {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "title": "plan",
                    "type": "object",
                    "properties": {
                      "plan_id": {
                        "type": "string"
                      },
                      "windows": {
                        "type": "array",
                        "items": {
                          "title": "cwindow",
                          "type": "object",
                          "properties": {
                            "charge": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "charge"
                          ]
                        }
                      },
                      "aggregated_usage": {
                        "type": "array",
                        "minItems": 1,
                        "items": {
                          "title": "pmetric",
                          "type": "object",
                          "properties": {
                            "metric": {
                              "type": "string"
                            },
                            "windows": {
                              "type": "array",
                              "items": {
                                "title": "pwindow",
                                "type": "object",
                                "properties": {
                                  "quantity": {
                                    "type": "number"
                                  },
                                  "summary": {
                                    "type": "number"
                                  },
                                  "cost": {
                                    "type": "number"
                                  },
                                  "charge": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "quantity",
                                  "summary",
                                  "cost",
                                  "charge"
                                ]
                              }
                            }
                          },
                          "required": [
                            "metric",
                            "windows"
                          ],
                          "additionalProperties": false
                        },
                        "additionalItems": false
                      }
                    },
                    "required": [
                      "plan_id",
                      "windows",
                      "aggregated_usage"
                    ],
                    "additionalProperties": false
                  },
                  "additionalItems": false
                }
              },
              "required": [
                "resource_id",
                "windows",
                "aggregated_usage",
                "plans"
              ],
              "additionalProperties": false
            },
            "additionalItems": false
          },
          "consumers": {
            "type": "array",
            "minItems": 1,
            "items": {
              "title": "consumer",
              "type": "object",
              "properties": {
                "consumer_id": {
                  "type": "string"
                },
                "windows": {
                  "type": "array",
                  "items": {
                    "title": "cwindow",
                    "type": "object",
                    "properties": {
                      "charge": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "charge"
                    ]
                  }
                },
                "resources": {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "title": "resource",
                    "type": "object",
                    "properties": {
                      "resource_id": {
                        "type": "string"
                      },
                      "windows": {
                        "type": "array",
                        "items": {
                          "title": "cwindow",
                          "type": "object",
                          "properties": {
                            "charge": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "charge"
                          ]
                        }
                      },
                      "aggregated_usage": {
                        "type": "array",
                        "minItems": 1,
                        "items": {
                          "title": "rmetric",
                          "type": "object",
                          "properties": {
                            "metric": {
                              "type": "string"
                            },
                            "windows": {
                              "type": "array",
                              "items": {
                                "title": "rwindow",
                                "type": "object",
                                "properties": {
                                  "quantity": {
                                    "type": "number"
                                  },
                                  "summary": {
                                    "type": "number"
                                  },
                                  "charge": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "quantity",
                                  "summary",
                                  "charge"
                                ]
                              }
                            }
                          },
                          "required": [
                            "metric",
                            "windows"
                          ],
                          "additionalProperties": false
                        },
                        "additionalItems": false
                      },
                      "plans": {
                        "type": "array",
                        "minItems": 1,
                        "items": {
                          "title": "plan",
                          "type": "object",
                          "properties": {
                            "plan_id": {
                              "type": "string"
                            },
                            "windows": {
                              "type": "array",
                              "items": {
                                "title": "cwindow",
                                "type": "object",
                                "properties": {
                                  "charge": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "charge"
                                ]
                              }
                            },
                            "aggregated_usage": {
                              "type": "array",
                              "minItems": 1,
                              "items": {
                                "title": "pmetric",
                                "type": "object",
                                "properties": {
                                  "metric": {
                                    "type": "string"
                                  },
                                  "windows": {
                                    "type": "array",
                                    "items": {
                                      "title": "pwindow",
                                      "type": "object",
                                      "properties": {
                                        "quantity": {
                                          "type": "number"
                                        },
                                        "summary": {
                                          "type": "number"
                                        },
                                        "cost": {
                                          "type": "number"
                                        },
                                        "charge": {
                                          "type": "number"
                                        }
                                      },
                                      "required": [
                                        "quantity",
                                        "summary",
                                        "cost",
                                        "charge"
                                      ]
                                    }
                                  }
                                },
                                "required": [
                                  "metric",
                                  "windows"
                                ],
                                "additionalProperties": false
                              },
                              "additionalItems": false
                            }
                          },
                          "required": [
                            "plan_id",
                            "windows",
                            "aggregated_usage"
                          ],
                          "additionalProperties": false
                        },
                        "additionalItems": false
                      }
                    },
                    "required": [
                      "resource_id",
                      "windows",
                      "aggregated_usage",
                      "plans"
                    ],
                    "additionalProperties": false
                  },
                  "additionalItems": false
                }
              },
              "required": [
                "consumer_id",
                "windows",
                "resources"
              ],
              "additionalProperties": false
            },
            "additionalItems": false
          }
        },
        "required": [
          "space_id",
          "windows",
          "resources",
          "consumers"
        ],
        "additionalProperties": false
      },
      "additionalItems": false
    }
  },
  "required": [
    "id",
    "organization_id",
    "start",
    "end",
    "processed",
    "windows",
    "resources",
    "spaces"
  ],
  "additionalProperties": false
}

Resource instance usage summary report

The resource instance usage summary report API can be used to retrieve aggregated usage summary report documents for a resource instance from Abacus.

Method: get

HTTP request:

GET /v1/metering/organizations/:organization_id/resource_instances/:resource_instance_id/consumers/:consumer_id/plans/:plan_id/metering_plans/:metering_plan_id/rating_plans/:rating_plan_id/pricing_plans/:pricing_plan_id/aggregated/usage/:time

Description: Retrieves a usage report document containing a summary of the aggregated Cloud resource usage incurred by the specified resource instance within an organization and the specific set of plans at the specified time.

HTTP response: 200 to indicate success with a usage summary report JSON document, 404 if the usage is not found, 500 to report a server error.

JSON representation:

{
  "start": 1435622400000,
  "end": 1435708799999,
  "processed": 1435708800000,
  "organization_id": "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
  "plan_id": "basic",
  "metering_plan_id": "test-metering-plan",
  "rating_plan_id": "test-rating-plan",
  "pricing_plan_id": "test-pricing-basic",
  "consumer_id": "app:d98b5916-3c77-44b9-ac12-045678edabae",
  "resource_instance_id": "0b39fa70-a65f-4183-bae8-385633ca5c87",
  "space_id": "aaeae239-f3f8-483c-9dd0-de5d41c38b6a",
  "resource_id": "object-storage",
  "accumulated_usage": [
    {
      "metric": "storage",
      "windows": [
        [{
          "quantity": 1,
          "summary": 1,
          "cost": 1,
          "charge": 1
        }],
        [{
          "quantity": 1,
          "summary": 1,
          "cost": 1,
          "charge": 1
        }],
        [{
          "quantity": 1,
          "summary": 1,
          "cost": 1,
          "charge": 1
        }],
        [{
          "quantity": 1,
          "summary": 1,
          "cost": 1,
          "charge": 1
        }],
        [{
          "quantity": 1,
          "summary": 1,
          "cost": 1,
          "charge": 1
        }]
      ]
    },
    {
      "metric": "thousand_light_api_calls",
      "windows": [
        [{
          "quantity": 3,
          "summary": 3,
          "cost": 0.09,
          "charge": 0.09
        }],
        [{
          "quantity": 3,
          "summary": 3,
          "cost": 0.09,
          "charge": 0.09
        }],
        [{
          "quantity": 3,
          "summary": 3,
          "cost": 0.09,
          "charge": 0.09
        }],
        [{
          "quantity": 3,
          "summary": 3,
          "cost": 0.09,
          "charge": 0.09
        }],
        [{
          "quantity": 3,
          "summary": 3,
          "cost": 0.09,
          "charge": 0.09
        }]
      ]
    },
    {
      "metric": "heavy_api_calls",
      "windows": [
        [{
          "quantity": 300,
          "summary": 300,
          "cost": 45,
          "charge": 45
        }],
        [{
          "quantity": 300,
          "summary": 300,
          "cost": 45,
          "charge": 45
        }],
        [{
          "quantity": 300,
          "summary": 300,
          "cost": 45,
          "charge": 45
        }],
        [{
          "quantity": 300,
          "summary": 300,
          "cost": 45,
          "charge": 45
        }],
        [{
          "quantity": 300,
          "summary": 300,
          "cost": 45,
          "charge": 45
        }]
      ]
    }
  ],
  "windows": [
    [{
      "charge": 46.09,
    }],
    [{
      "charge": 46.09,
    }],
    [{
      "charge": 46.09,
    }],
    [{
      "charge": 46.09,
    }],
    [{
      "charge": 46.09,
    }]
  ],
  "id": "k/us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27/0b39fa70-a65f-4183-bae8-385633ca5c87/app:d98b5916-3c77-44b9-ac12-045678edabae/basic/test-metering-plan/test-rating-plan/test-pricing-basic/t/0001435622400000",
}

JSON schema:

{
  "title": "resourceInstanceReport",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "start": {
      "type": "integer",
      "format": "utc-millisec"
    },
    "end": {
      "type": "integer",
      "format": "utc-millisec"
    },
    "processed": {
      "type": "integer",
      "format": "utc-millisec"
    },
    "organization_id": {
      "type": "string"
    },
    "space_id": {
      "type": "string"
    },
    "resource_instance_id": {
      "type": "string"
    },
    "consumer_id": {
      "type": "string"
    },
    "plan_id": {
      "type": "string"
    },
    "metering_plan_id": {
      "type": "string"
    },
    "rating_plan_id": {
      "type": "string"
    },
    "pricing_plan_id": {
      "type": "string"
    },
    "accumulated_usage": {
      "type": "array",
      "items": {
        "title": "accumulated",
        "type": "object",
        "properties": {
          "metric": {
            "type": "string"
          },
          "windows": {
            "type": "array",
            "items": {
              "title": "pwindow",
              "type": "object",
              "properties": {
                "quantity": {
                  "type": "number"
                },
                "summary": {
                  "type": "number"
                },
                "cost": {
                  "type": "number"
                },
                "charge": {
                  "type": "number"
                }
              },
              "required": [
                "quantity",
                "summary",
                "cost",
                "charge"
              ]
            }
          }
        }
      },
      "required": [
        "metric",
        "windows"
      ]
    },
    "windows": {
      "type": "array",
      "items": {
        "title": "cwindow",
        "type": "object",
        "properties": {
          "charge": {
            "type": "number"
          }
        },
        "required": [
          "charge"
        ]
      }
    }
  },
  "required": [
    "id",
    "organization_id",
    "space_id",
    "resource_instance_id",
    "consumer_id",
    "resource_id",
    "plan_id",
    "metering_plan_id",
    "rating_plan_id",
    "pricing_plan_id",
    "start",
    "end",
    "processed",
    "accumulated_usage",
    "windows"
  ],
  "additionalProperties": false
}

GraphQL usage query

The GraphQL usage query API can be used to query aggregated usage using the GraphQL query language.

Abacus defines a GraphQL schema for aggregated usage, allowing users to navigate and query the graph of aggregated usage within organizations and the spaces and resources they contain using the GraphQL query language.

The GraphQL schema listed below describes the graph used to represent aggregated usage, as well as the supported usage queries.

See the GraphQL documentation for more information on the GraphQL schema and query languages.

Method: get

HTTP request:

GET /v1/metering/aggregated/usage/graph/:query

Description: Retrieves a usage report document containing a summary of the Cloud resource usage matching the specified GraphQL query.

HTTP response: 200 to indicate success with a usage summary report JSON document, 404 if the usage is not found, 500 to report a server error.

Example GraphQL queries:

{
  organization(
    organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
    time: 1435622400000) {
      organization_id,
      resources {
        resource_id,
        aggregated_usage {
          metric,
          windows {
            quantity
          }
        }
      }
    }
}

{
  organization(
    organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
    time: 1435622400000) {
      organization_id,
      spaces {
        space_id,
        resources {
          resource_id,
          aggregated_usage {
            metric,
            windows {
              quantity
            }
          }
        }
      }
    }
}

{
  organization(
    organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
    time: 1435622400000) {
      organization_id,
      spaces {
        space_id,
        consumers {
          consumer_id,
          resources {
            resource_id,
            aggregated_usage {
              metric,
              windows {
                quantity
              }
            }
          }
        }
      }
    }
}

{
  organization(
    organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
    time: 1435622400000) {
      organization_id,
      spaces {
        space_id,
        consumers {
          consumer_id
        }
      }
    }
}

{
  organization(
    organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
    time: 1435622400000) {
      organization_id,
      resources {
        resource_id,
        aggregated_usage {
          metric,
          windows {
            quantity
          }
        }
      }
    }
}

{
  organizations(
    organization_ids: [
      "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",                                      
      "us-south:b3d7fe4d-3cb1-4cc3-a831-ffe98e20cf28"],
    time: 1435622400000) {
      organization_id,
      resources {
        resource_id,
        aggregated_usage {
          metric,
          windows {
            quantity
          }
        }
      }
    }
}

{
  account(
    account_id: "1234",
    time: 1435622400000) {
      organization_id,
      resources {
        resource_id,
        aggregated_usage {
          metric,
          windows {
            quantity
          }
        }
      }
    }
}

{
  resource_instance(
    organization_id: "us-south:a3d7fe4d-3cb1-4cc3-a831-ffe98e20cf27",
    consumer_id: "bbeae239-f3f8-483c-9dd0-de6781c38bab",
    resource_instance_id: "0b39fa70-a65f-4183-bae8-385633ca5c87",
    plan_id: "basic",
    time: time: 1435622400000) {
      organization_id,
      space_id,
      resource_id,
      resource_instance_id,
      plan_id,
      accumulated_usage {
        metric,
        windows {
          summary,
          charge
        }
      }
    }
}

GraphQL schema:

type ChargeWindow {
  charge: Float
}

type PlanWindow {
  quantity: Float
  cost: Float
  summary: Float
  charge: Float
}

type PlanMetric {
  metric: String
  windows: [[PlanWindow]]
}

type Plan {
  plan_id: String
  windows: [[ChargeWindow]]
  aggregated_usage: [PlanMetric]
}

type ResourceWindow {
  quantity: Float
  summary: Float
  charge: Float
}

type ResourceMetric {
  metric: String
  windows: [[ResourceWindow]]
}

type Resource {
  resource_id: String
  windows: [[ChargeWindow]]
  aggregated_usage: [ResourceMetric]
  plans: [Plan]
}

type Consumer {
  consumer_id: String
  windows: [[ChargeWindow]]
  resources: [Resource]
}

type Space {
  space_id: String
  windows: [[ChargeWindow]]
  resources: [Resource]
  consumers: [Consumer]
}

type OrganizationReport {
  id: String
  start: Int
  end: Int
  organization_id: String
  windows: [[ChargeWindow]]
  resources: [Resource]
  spaces: [Space]
}

type resourceInstanceReport {
  id: String
  start: Int
  end: Int
  organization_id: String
  space_id: String
  resource_id: String
  resource_instance_id: String
  consumer_id: String
  plan_id: String
  windows: [[ChargeWindow]]
  accumulated_usage: [PlanMetric]
}

type Query {
  organization(
    organization_id: String!,
    time: Int) : OrganizationReport

  organizations(
    organization_ids: [String],
    time: Int) : [OrganizationReport]

  account(
    account_id: String!,
    time: Int) : [OrganizationReport]
}