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:

Create an API key from the API Integrations Keys page and insert it where indicated in the code block below.

Advanced Analytics & API Monetization

Pre-requisites before using sample code below.

Create an API Asset in Revenium, or use an auto-detected API asset that was created from your previous traffic.
Create an API Product in Revenium and assign the asset you created to the product you just created.
- For monetization use cases, API Products group together Assets into sellable bundles and assign a pricing plan to the bundle.
- For productization & advanced API analytics, products are used in conjunction with Product Licenses & Consumer Applications (steps 3 & 4) to link API subscribers to your APIs.\
Create an API Product License in Revenium for the Product you created in step 2.
- Product Licenses are used to grant individual end users 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.\
Create or select & edit a pre-existing Consumer Application in Revenium with the following options:
1. select the product license 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 customers' applications to access your API, but for testing, we can use an arbitrary value)
  - Note that multiple Applications can share the same product license, which allows you to share a single license among a number of different end users 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 product license without requiring a separate credential to be provided to Revenium in the headers of the end user's API call.
Access your API key from the API Integrations Keys page
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": "https://test-asset.com/test/",
  "application": "test-application-api-key",
  "contentType": "application/json",
  "httpProtocol": "HTTP/1.0",
  "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://asset.com/verification/2",# INSERT THE URI or URL OF YOUR API ENDPOINT
  "application": "INSERT YOUR APPLICATION API KEY HERE",# INSERT EXTERNAL API KEY FROM YOUR APPLICATION
  "contentType": "application/json",
  "httpProtocol": "HTTP/1.0",
  "method": "POST",#AUTOMATICALLY GENERATED 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,# SAME AS ABOVE Re: AUTOMATIC GENERATION FROM GATEWAY POLICIES
  "gatewayLatency": 1.05,# SAME AS ABOVE
  "responseCode": 200,# SAME
  "remoteHost": "8.8.8.8",#ALLOWS REPORTING OF API ACCESS BY-GEO-LOCATION (automatically generated by gateway policies)
  "timedOut": false,# SAME
  "requestMessageSize": 200,# SAME
  "responseMessageSize": 300# SAME: NOTE THE FINAL LINE IN YOUR CALL SHOULD NOT HAVE A TRAILING COMMA
  "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.

url : This path will be saved in Revenium and all future traffic with the same URL will be stored under this record.

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 users 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.

Last updated 4 days ago