API Service Management v1.1 | 3scale: Free & Enterprise API Management Platform

3scale API for Service Management

API version 1.1 (the documentation for the previous version is here).

The other way to integrate your API with our API Management solution is to use the 3scale REST API for authenticating calls and reporting usage.

Documentation

This document describes the protocol used for your API to communicate with 3scale backend server for validating and reporting transactions between your infrastructure and your API users.

“In account” help

Remember that you can also use the “help” menu item from within your account (top right in the login box) to activate in-account help. This contains configuration information and also links to all the areas of the account you need to interact with.

Definitions

transaction: The process consisting of receiving a user’s request, processing it and sending a the response back to the user.
resource: Anything that is spent during execution of the transaction and that can be measured. This can be for example amount of CPU time spent during the processing, or amount of storage space used for storing some data, and so on.
provider authentication key: Key that uniquely identifies the provider in the 3scale backend.
provider verification key: Key used by user to verify authenticity of the provider.
user key: Key that uniquely identifies the user.

Operations

The API exposes a simple REST-based interface that provides these operations: authorize, and report.

AUTHORIZE

This is a read-only operation that checks if given key is valid and active and that the usage reported for the user corresponding to the key is not over the limits.

GET /transactions/authorize.xml?user_key=<user_key>&provider_key=<provider_key>

Parameters

provider_key: (required) Provider authentication key
user_key: (required) user key

Successful Response

Has status code 200 OK and a body containing the plan type and status information on the plan with one entry for every current metric limit (times are all UTC).


 <status>

  <plan>Pro</plan>

  <usage metric="hits" period="month">
    <period_start>2009-08-01 00:00:00</period_start>

    <period_end>2009-08-31 23:59:59</period_end>
    <current_value>17344</current_value>
    <max_value>20000</max_value>

  </usage>

  <usage metric="hits" period="day">
    <period_start>2009-08-19 00:00:00</period_start>

    <period_end>2009-08-19 23:59:59</period_end>
    <current_value>732</current_value>
    <max_value>1000</max_value>

  </usage>

  <usage metric="hits" period="hour">
    <period_start>2009-08-19 22:00:00</period_start>

    <period_end>2009-08-19 22:59:59</period_end>
    <current_value>26</current_value>
    <max_value>100</max_value>

  </usage>
 </status>

Errors

In case of error, the response body contains an XML-formatted object with a single element error. This element has one attribute id containing a unique string identifier of the error. The content of this element is a human-readable English description of the error.

These are all possible error identifiers and their meanings:

provider.invalid_key: Provider authentication key is not valid
user.exceeded_limits: Usage limits specified for contract are exceeded
user.invalid_key: User key is not valid
user.inactive_contract: User’s contract is not active
system.other: Some other unexpected error on the 3scale backend system

This is an example of an error response:


<?xml version=“1.0” encoding=“utf-8” ?>
<error id=“user.invalid_key”>user_key is invalid</error>

Example Request



GET /transactions/authorize.xml?user_key=3scale-709deaace57e31af33878207ecdf7a5d&provider_key=3scale-3a68df38cb310b2688b967f6e2cb1af6 HTTP/1.1

Host: backend.3scale.net

REPORT

This operation is used to report 3scale system about transactions. Any number of transactions can be reported in one request.

POST /transactions.xml

Parameters

transactions: (required) List of parameters for each transaction in the batch. More details are explained below.
provider_key: (required) Provider authentication key

The structure of the transactions parameter

The transactions should contain numerically indexed list of records, one for each transaction. Each record can contain these parameters:

user_key: (required) user key
usage: (required) usage data of the transaction. This should be associative array (a hash) of the form: {metric => value, ...}, where metric is name of the metric that measures the particular resource (for example “storage” or “hits”) and value is any amount of the corresponding resource spend in the transaction.
timestamp: (optional) if given, should be date and time when the transaction occured. It can be
specified in two ways: First, in UTC (Greenwitch time), second, in any other time zone.
In the first case, the timestamp has to be in this format: YYYY-MM-DD HH:MM:SS
for example 2009-01-01 17:45:02.
In the second case, the format has to be YYYY-MM-DD HH:MM:SS +HH:MM
or YYYY-MM-DD HH:MM:SS -HH:MM, where the +HH:MM
(or -HH:MM) part specifies the time offset from UTC in hours and minutes. For example, for timestamp in PST (Pacific Standard Time), it should look like this: 2009-01-01 22:15:31 -08:00.

These parameters have to be encoded in HTTP POST request. The usual way to do it, is to “flatten” the nested data structure. Example:

Having these parameters for two transactions:



{

  "0": {

    "user_key": "3scale-bce4c8f4b6578e6c3491e6d941b5b522",

    "usage": {"hits": 1, "transfer": 4500},

    "timestamp": "2009-01-01 14:23:08"},
  "1": {

    "user_key": "3scale-bad7e48018dc6f071ef9aabfe3229f97",

    "usage": {"hits": 1, "transfer": 2840},

    "timestamp": "2009-01-01 18:11:59"}}

They have to be encoded like this:


transactions[0][user_key]=3scale-bce4c8f4b6578e6c3491e6d941b5b522&
transactions[0][usage][hits]=1&
transactions[0][usage][transfer]=4500&
transactions[0][timestamp]=2009-01-01%2014%3A23%3A08&
transactions[1][user_key]=3scale-bad7e48018dc6f071ef9aabfe3229f97&
transactions[1][usage][hits]=1&
transactions[1][usage][transfer]=2840&
transactions[1][timestamp]=2009-01-01%2018%3A11%3A59

(note that spaces are encoded as %20 and colons as %3A according to URL encoding rules)

The numeric indices are important, because they are used in case of errors, to map error to a transaction that caused it. They don’t have to be in order, but have to be unique.

Successful Response

Has status code 201 Created and no response body

Errors

If there is an error in processing of at least one transaction, no transaction is reported. The response in that case is XML document containing list of all errors. The status code 403 Forbidden is returned.

This is example of a response with errors for transactions with indices 3 and 15:


<?xml version=“1.0” encoding=“utf-8” ?>

<errors>
  <error id=“user.invalid_key” index=“3”>user_key is invalid</error>
  <error id=“user.inactive_contract” index=“15”>contract is not active</error>
</errors>

There is one <error> element per each error. The id attribute contain identifier of the error (see the table on top of this page for list of possible identifiers) and index is index of the transaction that caused the error.

These are all possible error identifiers and their meanings:

provider.invalid_key: Provider authentication key is not valid
provider.invalid_metric: One or more of the metrics in reported usage is not valid
user.invalid_key: User key is not valid
user.inactive_contract: User’s contract is not active
system.other: Some other unexpected error on the 3scale backend system

Example Request


POST /transactions.xml HTTP/1.1
Host: backend.3scale.net
Content-Type: application/x-www-form-urlencoded
Content-Length: 428

transactions[0][user_key]=3scale-bce4c8f4b6578e6c3491e6d941b5b522&
transactions[0][usage][hits]=1&
transactions[0][usage][transfer]=4500&
transactions[0][timestamp]=2009-01-01%2014%3A23%3A08&
transactions[1][user_key]=3scale-bad7e48018dc6f071ef9aabfe3229f97&
transactions[1][usage][hits]=1&
transactions[1][usage][transfer]=2840&
transactions[1][timestamp]=2009-01-01%2018%3A11%3A59&
provider_key=3scale-6085e39a9872a7dbfacdc6565b8a255a