# Custom Integrations Using Metering Beacons

## Introduction

Revenium Metering Beacons act as bulkheads or “shock absorbers” to collect API transaction telemetry. The telemetry data is buffered in the Metering Beacon’s cache and periodically synchronized to the Revenium Transaction Engine.

{% hint style="info" %}
Under normal circumstances you **should not** need to implement custom integrations to the Metering Beacons. Revenium offers out-of-the-box connectivity to most common API Gateways and API platforms, including MuleSoft, Kong, Apigee, Istio, Envoy, Spring Boot and others.
{% endhint %}

The Revenium Metering Beacon presents a very simple REST API that allows downstream applications, such as API gateway plugins or agents, to send API transaction telemetry via an HTTP POST operation with a JSON payload.

![Metering Beacon Architecture](https://lh4.googleusercontent.com/9_lO8Zq9mSPXBGGWGJ9c4QJmbgC_hNvcLwTPZ3L2QNke-2FFl3rjQEESqU7_xFEsLdgLVGKa0ogf5V_uR6R3ouNC0dqOKr9jD4qsUlqe5HczRnMf1te6k4G6ebCiQ8vLXp44YV2u)

In addition to the REST API Revenium also provides a pre-packaged JVM SDK to simplify integration with JVM based applications (Java, Scala, Clojure, Kotlin, etc.)

{% hint style="info" %}
The Revenium Metering SDK can be obtained from your Revenium Account Team.
{% endhint %}

## Using the Metering Beacon API

{% hint style="info" %}
The full Metering Beacon API documentation is located here: <https://revenium.readme.io/reference/meter>
{% endhint %}

### Metering Beacon Data Types

The Metering Beacon API uses the following JSON data types

#### MeteringRequestDTO

*MeteringRequestDTO* represents the result of a metered HTTP API transaction. *MeteringRequestDTOs* are created after the response has been received from a metered API. Use *MeteringRequestDTO* when you need to meter an API transaction after it has completed. This is used to **synchronously** meter an API transaction.

|            |                                                           |
| ---------- | --------------------------------------------------------- |
| **Field**  | **Description**                                           |
| api        | The Revenium API ID of the metered API                    |
| productKey | The Revenium ProductKey ID of the subscriber being billed |
| method     | The HTTP method being called                              |
| url        | The URL of the API being called                           |

#### ApiEventDTO

*ApiEventDTO* represents either the request or response of an HTTP API transaction of a metered API request. ApiEventDTOs are created when the HTTP request is received and when the API response has been completed. This is used to **asynchronously** meter an API transaction.

|               |                                                                |
| ------------- | -------------------------------------------------------------- |
| **Field**     | **Description**                                                |
| requestId     | A UUID used to correlate request and response API events       |
| eventType     | The type of event, can be either \_“REQUEST” \_or *“RESPONSE”* |
| api           | The Revenium API ID of the metered API                         |
| productKey    | The Revenium ProductKey ID of the subscriber being billed      |
| method        | The HTTP method being called                                   |
| currentMillis | Epoch timestamp of the event in milliseconds                   |
| uri           | The URL/URI of the API being called                            |
| elapsedTime   | The elapsed time (in milliseconds) of the event                |

#### Metering Beacon Endpoints

The Revenium Beacon API exposes the following endpoints:

|                        |            |                    |                                                                                                                                                                                                                                                |
| ---------------------- | ---------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint**           | **Method** | **Type**           | **Description**                                                                                                                                                                                                                                |
| /metering/v1/api/meter | POST       | MeteringRequestDTO | Insert an API Metering Transaction. This method is used to capture an atomic API request / response in a single class. Use this endpoint when metering API transactions after they’ve completed.                                               |
| /metering/v1/api/meter | GET        | LineItemDTO        | Return currently buffered API Metering Requests                                                                                                                                                                                                |
| /metering/v1/api/event | POST       | ApiEventDTO        | Insert an API Metering Event. This is used to record API requests and responses independently. Use this endpoint to meter API requests and responses separately. The Metering Beacon will correlate the independent events using the requestId |

{% hint style="info" %}
Revenium uses the /metering/v1/api/meter endpoint to implement metering policies / plugins for traditional API Gateway implementations such as MuleSoft, Kong and Apigee. We use the /metering/v1/api/event to implement metering policies / plugins for cloud API Gateway implementations like AWS and Azure which rely on serverless functionality.
{% endhint %}

## Examples

### CURL

The detailed example [on this page](https://docs.revenium.io/ai-and-api-monetization/readme/curl-commands-for-testing) shows how to use CURL to send metering requests via the command line.

### Kotlin

This example demonstrates a metering request sent via Kotlin using the Revenium JVM SDK.

```
val dto = MeteringDTO(apiId, request.getHeader(X-REVENIUM-PRODUCT-KEY), req.method, req.requestURL.toString())

val jsonRequest = mapper.writeValueAsString(dto)

val meteringResponse = client.post().uri(uri!!)
          .body(BodyInserters.fromValue(jsonRequest))
                    .exchange().block()
if (!meteringResponse!!.statusCode().is2xxSuccessful) {
    logger.warn("Failure POSTing metering data to $meteringUrl (${meteringResponse.statusCode()}):" +
                                " ${meteringResponse.bodyToMono<String>()}\n" + jsonRequest)
        }
}
```

### Lua

This example demonstrates a metering request sent via Lua using the REST API.

```
function envoy_on_response(response_handle)
    local api_client = response_handle:streamInfo():dynamicMetadata():get("revenium")["api_client"]
    local status = tonumber(response_handle:headers():get(":status"))
    if (api_client ~= nil and (status >= 200 and status <= 299)) then
        local method = response_handle:streamInfo():dynamicMetadata():get("revenium")["method"]
        local path = response_handle:streamInfo():dynamicMetadata():get("revenium")["path"]
        local scheme = response_handle:streamInfo():dynamicMetadata():get("revenium")["scheme"]
        local api = response_handle:metadata():get("revenium")
        local body = "api=" .. api .. "&productKey=" .. api_client .. "&method=" .. method .. "&url=" .. path
        local headers, response_body = response_handle:httpCall("revenium",
            {
                [":method"] = "POST",
                [":path"] = "/",
                [":authority"] = "revenium",
            },
            body, 5000)
        local ps_status = tonumber(headers[":status"])
        if (ps_status > 200 or ps_status > 299) then
            response_handle:logError("Could not post body to metering beacon: " .. body)
        else
            response_handle:logDebug("Successfully posted body to metering beacon: " .. body)
        end
    end
end
```