cURL Commands for Testing

Below are instructions & sample code explaining how to use Revenium's metering API to receive transactions from your application.

If you are not using one of Revenium's gateway integration plugins, Revenium's metering API (documentation link) allows you to send data directly to Revenium from your application, and the code below will give you a quick start guide on using the API to send transactional data to Revenium.

Revenium's metering API can be used in two ways: The first is for API observability and analytics (without monetization), and the second is to utilize both the monetization & observability functions.

The process & pre-requisites for sending transactions in each scenario is provided below.

API Observability (no monetization)

Pre-requisites before using sample code below:

1. Obtain your API key from the API Keys page in the application and insert it where indicated in the code block below. If you need to create a new key, you can do it via the API Integrations Keys page.

Advanced Analytics & API Monetization

Pre-requisites before using sample code below.

1. Create an API Source in Revenium, or use an auto-detected API source that was created from your previous traffic.

2. Create an API Product in Revenium and assign the source you created to the product you just created.

   • For monetization use cases, API Products group together Sources into sellable bundles and assign a pricing plan to the bundle.

   • For productization & advanced API analytics, products are used in conjunction with Subscriptions & Subscriber Credentials (steps 3 & 4) to link API subscribers to your APIs.\

3. Create a Subscription in Revenium for the Product you created in step 2.

   • Subscriptions are used to grant individual end subscribers a right to access your product and to meter usage of the product so that an invoice can be generated at the end of each settlement period.\

4. Create or select & edit a pre-existing Subscribers Credential in Revenium with the following options:

   1. Select the Subscription you just created while configuring the Application,

   2. Assign an arbitrary "External API Key" in that Application (in practice, this "External API Key" will be the identifier used by your Subscribers' applications to access your API, but for testing, we can use an arbitrary value)

      • Note that multiple Applications can share the same Subscription, which allows you to share a single subscription among a number of different end subscriber or applications from a given customer who may want to measure consumption individually for each application, but pay for all combined usage on a single invoice.

      • The External API Key of the Application is required so that Revenium can easily associate client application usage to a valid Subscription without requiring a separate credential to be provided to Revenium in the headers of the end subscriber's API call.

5. Access your API key from the API Integrations Keys page

6. Use the information from steps 1-5 and insert it where indicated in the "Complex cURL Example" code block below.

Sample cURL Commands

Note that you have to remove all of the # symbols and any text after the hash symbols in the sample code block before sending the cURL request. Lines that only contain a hash symbol should be completely removed before sending your request.

cURL Call for sending test API Transactions to Revenium

Note that the code to send a monetized or non-monetized API transaction is the same, Revenium will automatically apply monetization logic if a product & product license have been created and are associated with the application & asset sent in your call.

After the second code sample below, you will find an explanation of where you can obtain the variables in the code block that are specific to your account.

Basic Test cURL: Start Here

This basic code block only requires you to insert your API key and a test transaction will be sent to the platform using the values pre-populated below.

Insert your API key where indicated in row 4 below and then submit the transaction in a terminal. Next, verify the transaction was successful.

curl --request POST \
     --url 'https://api.revenium.io/meter/v1/api/meter' \
     --header 'content-type: application/json' \
     --header 'x-api-key: INSERT REVENIUM API INTEGRATION KEY HERE' \
     --data '
{
  "url": "/url-of-your-endpoint/example",
  "application": "any-unique-identifier-for-user-or-app-making-the-call",
  "method": "POST",
  "responseCode": 200
}
'

Once you've verified that the above command works, you can move on to the more complex example below if you would like to explore the additional metadata that can be sent with each transaction to generate additional analytics on your API usage.

Complex cURL Example

curl --request POST \
     --url 'https://api.revenium.io/meter/v1/api/meter' \
     --header 'content-type: application/json' \
     --header 'x-api-key: INSERT REVENIUM API INTEGRATION KEY HERE' \ #required
     --data '
{
  "url": "https:///fqdn-or-url-of-your-endpoint/example",# INSERT THE URI or URL OF YOUR API ENDPOINT
  "application": # INSERT EXTERNAL API KEY, OAUTH TOKEN, OR OTHER UNIQUE ID FOR THE USER MAKING THE CALL
  "method": "POST",#AUTOMATICALLY GENERATED (AG) FROM API GATEWAY POLICIES, OR CAN BE MANUALLY SENT FROM YOUR CODE  
  "responseCode": 200,#THE COMMA BEFORE THE # SIGN MUST BE REMOVED IF YOU DO NOT INCLUDE ANY OPTIONAL DATA BELOW
#
#  ***ALL DATA BELOW IS OPTIONAL***
#
  "backendLatency": 2.05,# AG FROM GATEWAYS
  "gatewayLatency": 1.05,# AG FROM GATEWAYS
  "responseCode": 200,# AG FROM GATEWAYS
  "timedOut": false, # AG FROM GATEWAYS
  "remoteHost": "8.8.8.8",#ALLOWS REPORTING OF API ACCESS BY-GEO-LOCATION (AG FROM GATEWAYS)
  "requestMessageSize": 200,# AG FROM GATEWAYS
  "responseMessageSize": 300,# AG FROM GATEWAYS (double-check final trailing comma for the last item sent)
  "elements": [{"name": "yourElementName",
              "value": "yourElementValue"}]
}
'

Row 4: x-api-key - This is your Revenium integration key specific to your account. Create an API key from the API Integrations Keys page and use it here.

• Row 7: url - All metadata related to this transaction will be saved and associated with this URL. Future traffic with the same URL will be stored under this same record.

• Row 8: application - This maps to "Consumer Applications" in the Revenium UI. Enter the External API Key that you created in in your Revenium application in the pre-requisites section. (In production, this identifier generally maps to an API key or OAuth 2.0 Client ID used by your application to identify your users.) By providing this parameter, Revenium can provide combined reporting on all usage from the same application.

• Rows 11 - 22: metadata, method, backendLatency, gatewayLatency, responseCode, timedOut, requestMessageSize, responseMessageSize - data for all of these fields is automatically sent to our platform and used for analytics when using one of our gateway integrations, but any data you have can also be sent directly from your application by populating these attributes in the API call.

  • Note that of all the items from rows 11-22, only** method and responseCode **are required for every API call, the rest of these fields are optional.

  • An explanation of the elements portion of the call can be found under Metering Elements

• The complete reference documentation for parameters that can be sent to the metering API can be found here.

Viewing Test Transaction Data in Revenium

Once you have sent test transactions using the code above, after approximately two minutes, you will see a record of these transactions in the Analytics Transaction Log. Productized transactions will also generate additional logging data in the Product Transaction Log.

Be aware that API Product Transactions are only metered for requests with a 200 series response code. This is to prevent charging your subscribers for transactions that do not complete successfully in API monetization use cases. Basic API analytics will be captured in the Analytics Transaction Log regardless of the response code.

Troubleshooting

If you do not see evidence of your logged transactions after 5 minutes, you can look for errors in the System Logs to help troubleshoot why your traffic is not being properly received.

Additional Integration Options

Additional custom integration options are explained in the following section.