API - Service Management

API version 1.1.3

3scale lets you delegate all the administrative aspects so you can concentrate on the core of your web-services. Once you have registered your web-service and created a contract, you will need a simple adaptation of your web-service to become compatible with the 3scale contract management back-end.

There are two ways of integrating 3scale into your web-service. One is by installing one of our plugins (dependent on the language/framework you are using), another is by using our API directly. This section provides the information for the later.

Specification

This document describes the protocol used for communication with 3scale backend server for validating and reporting transactions between user and provider of a service.

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: start, confirm and cancel, for single transaction reporting, and authorize and batch report for multiple (batch) transaction reporting.

Every operation can respond with success or an error. The successful responses are described in the following sections. If there is an 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

provider.invalid_metric

One or more of the metrics in reported usage is not valid

provider.invalid_transaction_id

Given transaction id does not correspond to any existing transaction

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 example of error response:

START

This operation is used to notify 3scale backend that a transaction has been started. It can be optionally used to predict the resource usage of a transaction. This should be called before the request processing is started.

POST /transactions.xml

Parameters

provider_key

(required) Provider authentication key

user_key

(required) user key

usage

(optional) Predicted resource usage of this transaction. This should be
associative array (a hash) of the form: {metric => value, ...},
where metric is name of the metric that measures particular
resource (for example “storage” or “hits”) and
value is any amount of corresponding resource that is
expected to be spend.

This parameter may contain only approximate values, or it can be left
out entirely. In that case, the actual usage should be reported
in Confirm operation, described in the next section.

Successful Response

Has Status code 200 OK and in the response body contains XML-formatted object that looks like this:

id

Identifier of the transaction. This is needed for
confirmation/cancelation of the transaction later

contract_name

Name of contract the user has signed for. The provider can use this
information for example to send different results back to the user
according to contract types the user signed up for if desired. (e.g.
returning larger result sets to Pro customers and smaller result
sets to Free customers).

provider_verification_key

This key should be sent back to user, so the provider’s authenticity can be verified.

Errors

• » Status code 400 Bad Request with error identifier provider.invalid_metric
• » Status code 403 Forbidden with one of these
  error identifiers:
• » user.inactive_contract
• » user.invalid_key
• » user.exceeded_limits
• » provider.invalid_key
• » Status code 500 Internal Server Error with error identifier system.other

In case of an error, the processing of the request should be stopped and user should be notified about the error.

Examples Request

CONFIRM

This operation is used to confirm a previously started transaction. It should be executed after the request has been successfully processed and is ready to be sent back to the user. After this operation, the usage data are confirmed and used for cost calculation and statistics.

POST /transactions/<transaction_id>/confirm.xml

Parameters

transaction_id

(this is part of the path, required) Identifier of the transaction,
obtained by previous “Start” operation

provider_key

(required) Provider authentication key

usage

(optional) Actual resource usage. This should be used only when the
predicted resource usage was missing or inaccurate.

Successful Response

Has status code 200 OK and no response body

Errors

• » Status code 400 Bad Request with error
  identifier provider.invalid_metric
• » Status code 403 Forbidden with error
  identifier provider.invalid_key
• » Status code 404 Not Found with error
  identifier provider.invalid_transaction_id
• » Status code 500 Internal Server Error with error
  identifier system.other

Example Request

CANCEL

This operation is used to cancel a previously started transaction. This should be used when an error occurs during execution, and the request cannot be fulfilled. This deletes the previously created predicted usage data.

DELETE /transactions/<transaction_id>.xml

Parameters

transaction_id

(this is part of the path, required) Identifier of the transactions,
obtained by previous “Start” operation

provider_key

(required) Provider authentication key. Because DELETE requests do not
contain a body, this parameter should be appended as part of a query string.
(see the example)

Successful Response

Has status code 200 OK and no response body

Errors

• » Status code 403 Forbidden with error identifier
  provider.invalid_key
• » Status code 404 Not Found with error identifier
  provider.invalid_transaction_id
• » Status code 500 Internal Server Error with error
  identifier system.other

Example Request

Note About Non-compliant Clients

Some HTTP clients do not support the DELETE method. For these clients, the fallback solution is to use the POST method and an additional parameter
_method with value “delete”. Example:

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>&amp;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

• » Status code 403 Forbidden with one of these error identifiers:
• » user.inactive_contract
• » user.invalid_key
• » user.exceeded_limits
• » provider.invalid_key
• » Status code 500 Internal Server Error with error identifier system.other

Example Request

BATCH REPORT

This operation is used to report multiple transactions in one batch. This can be used to reduce the amount of traffic between the provider and 3scale backend servers thus improving performance.

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 has the same format as described under start and confirm operations.

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 could 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:

They have to be encoded like this:

(note that spaces are encoded as %20 according to URL encoding rules)

The numeric indices are important, because they are used when returning errors. 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:

There is one <var>&lt;error&gt;</var> 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.

Example Request

Plugins

To avoid having to implement the connection to the API yourself, check out the list of plugins to make this easier. Let us know using the feedback form on the left if you have any problems with the API or the plugins so we can help you get connected as easily as possible.