API-based Method

Overview

Usage record can be collected to Paigo by Paigo's public REST API. Among other usage measurement and collection methods, API-based measurement is the most flexible method while requires most maintenance work and taking longest time to deliver value. For comparison with other usage measurement and collection methods, see Meter Usage Data at Scale chapter for full documentation.

Data Record Schema

Paigo's usage record ingestion API /usage is designed with simplicity while allowing extensibility for product of various scale. Each individual usage record must be in JSON format that is compliant with the following schema and requirement:

{
  "timestamp": "string",
  "customerId": "string",
  "dimensionId": "string",
  "recordValue": "0.0",
  "metadata": {}
}

Requirement for each field:

• timestamp : REQUIRED. The timestamp of usage record in RFC3339 format with a 4-digit year. This is the time the usage occurred, or the end of the usage period. Example: 2021-01-23T01:23:45Z

• customerId: REQUIRED. The Customer ID of a customer this usage record attributes to, assigned by Paigo during customer creation. Example: e8366954-6f36-47e9-8431-ac95f88b5cc7.

• dimensionId: REQUIRED. The unique identifier of the dimension this usage record is associated with.

• recordValue : REQUIRED. The amount of the usage on this record. Numerical values are represented as strings to avoid precision loss.

• metadata : Key-value pairs used for analytical purpose. Example {"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe"}

For detailed information on response, payload, and other API spec, see API Docs. To construct a usage record payload for API-based method, use Paigo dashboard to try creating a usage record, and copy code from the Preview section at the end of the page to get started. See Ingest Usage Record with Dashboard for more information.

Leveraging Metadata

Additional metadata to be stored on the usage record, such as environment, purpose, owner, developer, contract number, or any arbitrary data to be associated with this usage record. Metadata can be used for analytics purpose in the future.