Sending Data to Revenium's Metering API

While Revenium offers a number of pre-built connectors and SDKs, as well as our Postman collection, you can also send data directly with our metering API, which is explained below.

This tutorial will guide you through the process of sending data to Revenium's Metering API using curl. We'll cover the main endpoints and provide examples for each. Finally, here is a link to complete API documentation.

Prerequisites

• curl installed on your system

• Your Revenium API key

Authentication

All requests to the Revenium Metering API require authentication using an API key. Include your API key in the x-api-key header with each request.

The terms in this document map to the v1 Revenium API, which don't always match with the terms used in the user interface. The forthcoming v2 API will map to Revenium's current lexicon. (full details)

Submitting API Metering Data

To submit API metering data, use the /meter endpoint.

The /meter endpoint is designed for the submission of API-specific monetization and analytics data to Revenium. It is typically used to send data after an API response is received. The data submitted to this endpoint encapsulates the metadata for a single API transaction, providing important details for monetization and observability purposes.

curl -X POST https://api.revenium.io/meter/v1/api/meter \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "api": "3c2c3d64-2f59-4642-9406-17d7fb5e2d5c",
    "method": "GET",
    "url": "https://api.example.com/v1/resource",
    "responseCode": 200,
    "requestHeaders": ["Content-Type", "Authorization"],
    "responseHeaders": ["Content-Type"],
    "elements": [
      {
        "name": "input-tokens",
        "value": "1928913"
      },
      {
        "name": "output-tokens",
        "value": "391029302"
      }
    ],
    "monetized": true
  }'

Replace YOUR_API_KEY with your actual Revenium API key.

Saving an API Event

To save an API event, use the /event endpoint.

The /event endpoint is similar to the /meter endpoint but is used to submit API requests and responses separately. Revenium will then correlate these requests and responses into a single API transaction that mirrors a request to the /meter endpoint. This endpoint is particularly useful for integrating with asynchronous or stateless API event data, such as from cloud gateways or logging systems.

Submitting an API Request Event

curl -X POST https://api.revenium.io/meter/v1/api/event \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '
  {
  "requestId": "3cbecf2a-edc6-4683-8934-a258d0fc3a09",
  "eventType": "REQUEST",
  "method": "POST",
  "currentMillis": 1685402319000,
  "uri": "/hammerhead-1",
  "source": "CUSTOM",
  "application": "4d0d8cae-c025-4a4c-907a-3efc0b4c41d1"
}'

Submitting an API Request Response

curl -X POST https://api.revenium.io/meter/v1/api/event \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '
  
  {
  "requestId": "3cbecf2a-edc6-4683-8934-a258d0fc3a09",
  "eventType": "RESPONSE",
  "method": "POST",
  "currentMillis": 1675308955000,
  "uri": "/hammerhead-1",
  "source": "CUSTOM",
  "application": "4d0d8cae-c025-4a4c-907a-3efc0b4c41d1"
  }'

Submitting Rating Events

To submit rating events, use the /meter/rate endpoint.

Compared to the metering endpoint, rating events do not contain analytics data, but allow for a simpler integration if you are only interested in counting & rating events from your application in Revenium. Rating Events are useful for metering and monetizing non-API centric data from sources like iPaaS applications, legacy billing systems, or Lambda functions.

curl -X POST https://api.revenium.io/meter/v1/api/meter/rate \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "sourceId": "example-source",
    "subscriberCredentialId": "user-123",
    "payload": {
      "rating": "5"
    },
    "sourceType": "app"
  }'

Ingesting Raw JSON Metering Data

To ingest raw JSON metering data, use the /meter/ingest endpoint.

Raw JSON metering is useful when the structure of the metering data is unknown in advance. Revenium will attempt to extract key/value pairs from the JSON payloads, which can then be configured as Metering Elements for monetization.

curl -X POST https://api.revenium.io/meter/v1/api/meter/ingest?sourceId=src-456&subscriptionId=sub-123 \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-revenium-source-type: custom" \
  -d '{"hotelRoomsBooked": "100", "carRentalCount": "242"}'

Validating a Subscription and Subscriber Credential

To check if a subscription or subscription credential is valid, use the /meter/product-key endpoint.

Checking if a Subscription is Valid

curl -X GET "https://api.revenium.io/meter/v1/api/meter/product-key \
?productKey=YOUR_SUBSCRIPTION_KEY" \
  -H "x-api-key: YOUR_API_KEY"

Checking if a Subscription Credential is Valid

curl -X GET "https://api.revenium.io/meter/v1/api/meter/product-key \
?application=YOUR_SUBSCRIPTION_CREDENTIAL" \
  -H "x-api-key: YOUR_API_KEY"

Replace YOUR_SUBSCRIPTION_KEY and YOUR_SUBSCRIPTION_CREDENTIAL with the actual values you want to validate.

You can find the subscription key using the 'key' field when viewing a subscription in the Revenium user interface. The value to use for your subscriber credential is the 'external ID' found in the Revenium UI when viewing a subscriber credential.

In either scenario the endpoint will return a 200 status code along with a JWT claim containing metadata about the subscription:

{
  "claim": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIeXBlckN1cnJlbnQiLCJvcmdhbml6YXRpb24iOiJIYW1tZXJoZWFkIENhY2hlIFRlc3RpbmciLCJjb25zdW1pbmdPcmdhbml6YXRpb24iOiJHaWJzb24gSGVhdnkgSW5kdXN0cmllcyIsImNvbnN1bWVyIjoiam9obi5kZW1pYytva3RhdGVzdDNAaHlwZXJjdXJyZW50LmlvIiwicHJvZHVjdCI6IlRQMDEiLCJwcm9kdWN0VGFncyI6W10sInByb2R1Y3RMaWNlbnNlVGFncyI6W10sInByb2R1Y3RWZXJzaW9uIjoiMS4wLjAiLCJhc3NldHMiOlsiVFMwMSJdLCJleHBpcmF0aW9uIjpudWxsLCJ0b3RhbFF1b3RhIjowLCJjb25zdW1lZFF1b3RhIjowLCJjb25zdW1lZFN1YnNjcmlwdGlvblF1b3RhIjowLCJzdWJzY3JpcHRpb25TdGFydCI6MTcyNjEwNTMxNjMyOCwic3Vic2NyaXB0aW9uUGVyaW9kU3RhcnQiOjE3MjY2MjQ4MDAwMDAsInN1YnNjcmlwdGlvblBlcmlvZEVuZCI6MTcyNjcxMTIwMDAwMCwiZWxlbWVudEFjY2Vzc0V2ZW50cyI6W10sInRpbWVzdGFtcCI6MTcyNjY5NjU4NDM1OX0.dtgOr6lNIabhvLrO6a6PT6oL3xRhneOljrudlgKZRcXASzIjt51mQV8D07c9EL52jLvlys4vmnivKHNs8ESZYiWvKOu3s07T-St_XGEK_96xOED_vY8VdlLhlFpnN2AE62db6slf9OiXOd4uWjHgyEGw8Sp9UWHs76keb_Ujl4Jt96l4rrKrg5aliNHX-Bn-Sn6TZJZKmqTxE9wMiL7XFsqaOsvtH74u99gELOhLWapFgKHObv5RFaCY25qwu_SgLxK1w8qdJgB4e8K55bEMjHv3HAdZlCyeAgGdu3-NBc3VbgSaYq6-_anvoPPekiibUg6XduERvyRuen_yxUN1bA"
}

If the subscription is invalid then a 404 response code will be returned.

Error Handling

If you encounter any errors, check the response body for error messages and details. Common HTTP status codes you might encounter include:

• 200: Successful request

• 400: Bad request (check your input data)

• 403: Unauthorized (check your API key)

Always ensure you're using the latest version of the API and refer to the official Revenium documentation for any updates or changes to the API endpoints and parameters.