API – Service Management v2.0 | 3scale: Free & Enterprise API Management Platform

API version 2.0 (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 authorizing and reporting transactions between your infrastructure and your API users.

Definitions

service: any web service implementing an API
provider: an organization, company or individual providing a service
application: a consumer endpoint of a web service (website, embeddable widget, desktop program, mobile application, HTTP enabled microwawe oven, …)
transaction: Single unit of interaction between an application and a service. In case of HTTP-base web services, this is usually one request-response exchange.
resource: Anything that is spent during a transaction and can be measured. This can be for example CPU time spent during the processing, or storage space used for storing some data, and so on.
metric: A way to measure a resource. For example: number of API hits, amout of disk space in megabytes, CPU time in miliseconds, …
provider key: Unique textual identifier of a provider.
application id: Public unique textual identifiier of an application.
application key: Secret key for authenticating transactions.

Operations

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

AUTHORIZE

Read-only operation to authorize an application. It is used to check if a particular application exists, is active and is within usage limits of the service. It can be optionally used to authenticate a call using an application key.

GET /transactions/authorize.xml?app_id={app_id}&provider_key={provider_key}[&app_key={app_key}]

Parameters

provider_key: Provider key. Required.
app_id: Application id. Required.
app_key: Application key. Required only if it is defined for the application.
referrer: Referrer IP Address or Domain. Required if referrer filtering is enabled. If special value “*” (start) is passed, the referrer check is bypassed.
no_body: Specify this parameter to remove the HTTP body from the response. Optional. Example: no_body=true
usage: Predicted usage. Optional

Predicted usage

It’s possible to pass a “predicted usage” to the authorize call. This can serve two purposes:

To make sure an API call won’t go over the limits before the call is made, if the usage of the call is known in advance. In this case, the estimated usage can be passed to the authorize call, and it will respond whether the actual API call is still within limit. In other words, without the usage parameter, authorize only checks the usage that has already been reported. If the usage parameter is passes in, it will check whether the already reported usage + the passed in predicted usage is still within limit.
To limit the authorization only to a subset of metrics. If usage is passed in, only the metrics listed in it will be checked against the limits. For example: There are two metrics defined: searches and updates. updates are already over limit, but searches are not. In this case, the user should still be allowed to do a search call, but not an update one. To authorize this, pass usage[searches]=1 to the authorize call.

NOTE: Even if the predicted usage is passed in, authorize is still a read-only operation. You have to make the report call to report the usage.

NOTE: usage is an associative array of the form {metric : value}. Please reffer to the “Encoding complex data structures in URLs” appendix for more info.

Successful Response

Has status code 200 OK (if authorization is granted), 409 (if it’s not granted) and a body containing authorization result, failure reason (if authorization failed), the plan type and list of usage report entries for every current metric limit. If the no_body parameter is specified, there is no body in the response.

Example of successful authorize response


<status>
  <authorized>true</authorized>
  <plan>Pro</plan>

  <usage_reports>
    <usage_report metric="hits" period="month">
      <period_start>2010-08-01 00:00:00 +00:00</period_start>
      <period_end>2010-09-01 00:00:00 +00:00</period_end>
      <current_value>17344</current_value>
      <max_value>20000</max_value>
    </usage_report>

    <usage_report metric="hits" period="day">
      <period_start>2010-08-04 00:00:00 +00:00</period_start>
      <period_end>2010-08-05 00:00:00 +00:00</period_end>
      <current_value>732</current_value>
      <max_value>1000</max_value>
    </usage_report>
  </usage_reports/>
</status>

Example of failed authorize response (exceeded limits)


<status>
  <authorized>false</authorized>
  <reason>Usage limits are exceeded</reason>
  <plan>Pro</plan>

  <usage_reports>
    <usage_report metric="hits" period="month">
      <period_start>2010-08-01 00:00:00 +00:00</period_start>
      <period_end>2010-09-01 00:00:00 +00:00</period_end>
      <current_value>17344</current_value>
      <max_value>20000</max_value>
    </usage_report>

    <usage_report metric="hits" period="day" exceeded="true">
      <period_start>2010-08-04 00:00:00 +00:00</period_start>
      <period_end>2010-08-05 00:00:00 +00:00</period_end>
      <current_value>1042</current_value>
      <max_value>1000</max_value>
    </usage_report>
  </usage_reports/>
</status>

Explanation of the elements

status: Root element of the response.
authorized: Contains text “true” if the authorization was successful, or “false” if it failed.
reason: Human readable textual description of failure reason. This element appears only if authorize is false.
plan: Name of the plan the user is signed up to.
usage_reports: Contains list of usage_report elements – one per each usage limit defined for the plan the user is signed up to.
usage_report: Contains information about usage status. Contains these elements: period_start, period_end, current_value and max_value. Has attributes metric with the name of the metric the limit applies to, period, which is the period of the limit (year, month, week, day, hour, minute) and optionaly exceeded which is set to “true” if the limit is exceeded in the current period.
period_start: Start of the limit period. It’s in the form YYYY-MM-DD HH:MM:SS +ZZ:ZZ. +ZZ:ZZ (or -ZZ:ZZ) is a time offset (in hours and minutes) from UTC.
period_end: End of the limit period. Same format as period_start
current_value: Value of the corresponding metric accumulated so far in the current period.
max_value: Maximum value allowed by the usage limit.

Errors

In case of error, the response body contains an XML-formatted object with a single element error. This element has one attribute code 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_key_invalid: Provider key is not valid
application_not_found: Application with the given id does not exist.

This is an example of an error response:


<?xml version=“1.0” encoding=“utf-8” ?>
<error code=“application_not_found">Application with id="12345678" was not found</error>

Example Request

GET /transactions/authorize.xml?app_id=709deaac&provider_key=3a68df38cb310b2688b967f6e2cb1af6&app_key=b854fa63c30c5b1bc8c0fce8da1b2cf3 HTTP/1.1

Host: su1.3scale.net

Example Request with referrer

GET /transactions/authorize.xml?app_id=709deaac&provider_key=3a68df38cb310b2688b967f6e2cb1af6&app_key=b854fa63c30c5b1bc8c0fce8da1b2cf3&referrer=example.org HTTP/1.1

Host: su1.3scale.net

Example Request with usage

GET /transactions/authorize.xml?app_id=709deaac&provider_key=3a68df38cb310b2688b967f6e2cb1af6&app_key=b854fa63c30c5b1bc8c0fce8da1b2cf3&usage[hits]=1&usage[transfer]=1024 HTTP/1.1

Host: su1.3scale.net

AUTHREP

“One-shot” operation to authorize an application and report traffic. The only difference between this call and the regular authorize call is that metric usage will be reported if the authorization is successful.

GET /transactions/authrep.xml?app_id={app_id}&provider_key={provider_key}[&app_key={app_key}]&usage[hits]=1

Parameters

provider_key: Provider key. Required.
app_id: Application id. Required.
app_key: Application key. Required only if it is defined for the application.
referrer: Referrer IP Address or Domain. Required if referrer filtering is enabled. If special value “*” (start) is passed, the referrer check is bypassed.
no_body: Specify this parameter to remove the HTTP body from the response. Optional. Example: no_body=true
usage: Metric usage. If the authorization succeeds and the application is still within the limits with this usage, it’s aggregated to the application statistics and usage limits.

Usage

The usage parameters should be passed along in order to report traffic.

This will make sure an API call won’t go over the limits. It will check whether the already reported usage + the passed in usage is still within limit.
If the authorization is successful the usage will then be “reported” and aggregated for statistics and usage limits purposes. There is no need to make a second call to report the traffic since this is already taken care of.

NOTE: usage is an associative array of the form {metric : value}. Please refer to the “Encoding complex data structures in URLs” appendix for more info.

Successful Response

Has status code 200 OK (if authorization is granted – and therefore reported), 409 (if it’s not granted) and a body containing authorization result, failure reason (if authorization failed), the plan type and list of usage report entries for every current metric limit. If the no_body parameter is specified, there is no body in the response.

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: List of parameters for each transaction in the batch. More details are explained below. Required.
provider_key: Provider key. Required.

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:

app_id: Application ID. Required.
usage: 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. Required.
timestamp: 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. Optional. If not specified, the time when the transaction was received is used.

These parameters have to be encoded in HTTP POST request using the application/x-www-form-urlencoded media type. Please reffer to the “Encoding complex data structures in URLs” appendix for more info.

Successful Response

Has status code 202 Accepted and no response body

Errors

Processing transactions, especially if there is lot of them, can be time consuming task. To achieve low response times, most of the processing is actually done offline. Fot this reason, there are two ways the errors are reported:

Errors detected during request processing

Only one type of error can occur during request processing – invalid provider key. In case the provider key is not valid, the response has status code 403 Forbidden and the body contains XML document with description of the error. Example:


<?xml version=“1.0” encoding=“utf-8” ?>
<error code="provider_key_invalid">Provider key "abcd1234" is invalid</error>

Errors detected during offline processing

If an error occurs during offline processing, it’s description is stored and can be examined by visiting the provider admin area on www.3scale.net.

Errors that can occur in the offline processing are:

invalid application id
invalid metric
invalid usage value
general parsing failure

Note that transactions from a single batch are reported only if all of them are valid. If there is an error in processing of at least one of them, none is reported.

Example Request


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

transactions[0][app_id]=bce4c8f4&
transactions[0][usage][hits]=1&
transactions[0][usage][transfer]=4500&
transactions[0][timestamp]=2009-01-01%2014%3A23%3A08&
transactions[1][app_id]=bad7e480&
transactions[1][usage][hits]=1&
transactions[1][usage][transfer]=2840&
transactions[1][timestamp]=2009-01-01%2018%3A11%3A59&
provider_key=6085e39a9872a7dbfacdc6565b8a255a

Appendix: Encoding complex data structures in URLs

The usual way to encode a complex data structure (array, associative array, nested structures) is to “flatten” it.

For example, having this structure:


{
  "0": {
    "app_id": "bce4c8f4",
    "usage": {"hits": 1, "transfer": 4500},
    "timestamp": "2009-01-01 14:23:08"},

  "1": {
    "app_id": "bad7e480",
    "usage": {"hits": 1, "transfer": 2840},
    "timestamp": "2009-01-01 18:11:59"}}

It has to be encoded like this:


transactions[0][app_id]=bce4c8f4&
transactions[0][usage][hits]=1&
transactions[0][usage][transfer]=4500&
transactions[0][timestamp]=2009-01-01%2014%3A23%3A08&
transactions[1][app_id]=bad7e480&
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)