REST API for the Metering Service

Introduction

This section is an overview of the REST API provided by the metering microservice.

• Users
• Recording usage
• Retrieving data

Users

POST /user

Body:

{
    "username": "...",
    "password": "..."
}

Response: 201 Created

Purpose: Adds a new tenant. Requires the ADMIN role. For more info about tenants please see architecture.

DELETE /user/

Response: 204 No Content

Purpose: Deletes the named tenant. Requires the ADMIN role. For more info about tenants please see architecture.

Recording usage

POST /usage/location

Request Body:

  {
    "ampId": "ADRES123",
    "locId": "LN4v2O8t",
    "date": <timestamp>,
    "state": "created",
    "entityId": "RNNIP0Nv",
    "entityType": "DSDWQ",            //nullable
    "applicationId": "RNNIP0Nv",
    "user": "PLPLP",                  //nullable
    "locationUsageMetadata": [
      {
        "name": "hardwareId",
        "value": "m3.large"
      },
      {
        "name": "imageId",
        "value": "ami-aejiedj3"
      }
      # etc, for other metadata about the VM
    ]
  }

Response: 201 Created

Purpose: Records a single location event for the tenant making the request. Please note, this location event is stored against the tenant making the call. When an admin queries the microservice for usage information they will provide a tenant ID to search against. This is separate from the user entry in the JSON. The user entry in the JSON is the user who is logged into AMP.

Description:

• Requires USER role
• Timestamp format yyyy-MM-dd’T’HH:mm:ssX
• Metadata may contain arbitrary key/value data.

POST /usage/locations

Request body:

  {
    "events": [
      { each object as above }  
    ]
  }

Response: 201 Created

Purpose: Record multiple location events.

POST /usage/application

Request body:

  {
    "date": <timestamp>,
    "state": "on-fire",
    "ampId": "asdasdafl",
    "applicationId": "koklflsdfs",
    "applicationName": "asdawewaxc",
    "entityType": "plplasd",
    "applicationUsageMetadata": [
      {
        "name": "displayName",
        "value": "riak cluster"
      }
      # etc, for other app metadata
    ]
  }

Response: 201 Created

Purpose: Record a single application event.

Description:

• Requires TENANT role
• Timestamp format yyyy-MM-dd’T’HH:mm:ssX
• Metadata may contain arbitrary key/value data.

POST /usage/applications

Request body:

  {
    "events": [
      { each object as above }  
    ]
  }

Response: 201 Created

Purpose: Record multiple application events.

Retrieving data

GET /usage/location/hour

Query Parameters:

• tenantId
• startTime
• endTime

Response format:

{
    "usage": [
        {
            "ampId": "AMP_ID_5",
            "applicationId": "APP_ID_1",
            "entityId": "ENTITY_ID_0",
            "hours": 00.00,
            "locId": "LOC_ID_0"
        },
        ...
    ]
}

Purpose: Retrieve a summary of the usage data for the named tenant between the given dates. Unlike /usage/location which returns each individual record, this endpoint returns one record per location adding up all periods for which the location was active. This endpoint is often used for calculuate biling information.

Description:

• All parameters are required.
• Requires the ADMIN role.
• Timestamp format yyyy-MM-dd’T’HH:mm:ssX

GET /usage/location-metadata

Query Parameters:

• locId
• startTime
• endTime

Response format:

[
    {
        "name": "location-metadata-name",
        "value": "location-metadata-value"
    }
]

Purpose: Retrieve a list of all metadata associated with a location over the given time period.

Description:

• All parameters are required
• Requires the ADMIN role
• Timestamp format yyyy-MM-dd’T’HH:mm:ssX

GET /usage/location

Query Parameters:

• tenantId
• ampId
• applicationId
• entityId
• locId
• user
• entityType
• state
• startTime
• endTime

Response format:

[
    {
        "ampId": "my_amp_id_1",
        "locId": "loc1",
        "date": "2017-03-29T14:12:37Z",
        "state": "CREATED",
        "entityId": "swu0whyw2w",
        "entityType": "org.apache.brooklyn.entity.software.base.EmptySoftwareProcess",
        "applicationId": "v5hbwhxizy",
        "user": "im_a_user",
        "locationUsageMetadata": [
            {
                "name": "displayName",
                "value": "localhost"
            },
            {
                "name": "parentDisplayName",
                "value": "localhost"
            }
        ]
    }
]

Purpose: Retrieve a list of LocationUsage events matching the search criteria. Search criteria are optional, allowing custom queries to be written.

Description:

• All query parameters are optional
• At least one parameter must be given
• Requires the ADMIN role
• Timestamp format yyyy-MM-dd’T’HH:mm:ssX