GreenArrow Engine Configuration API

Table of Contents
Authentication
Return Values
Rate Limits
Using curl

This is the documentation for the GreenArrow Engine Configuration API. If you have additional questions about the API or feel that you’ve encountered a bug, please don’t hesitate to contact us at our support address.

Interactions with this API are accomplished over HTTP. On POST and PUT requests, JSON is expected as the body of the request. All API calls reply with JSON.

Authentication

HTTP basic authentication is used. You should use a username and password that is authorized to log in to GreenArrow Engine’s web interface.

You can also use an API key: send the username api and the key as the password.

Return Values

All responses from the API will include the following keys.

success boolean	Returns `true` if the requested operation was carried out successfully and `false` otherwise.
data hash	The `data` hash will contain whatever response is defined in the specific API endpoint that is being called. If there is an error or if the endpoint returns no data, `null` is returned in this key.
error_code string	If `success` is `true`, this value is set to `null`. On failed queries, this value is set to one of the predefined error codes.
error_messages array of strings	If `success` is `true`, this value is set to `null`. On failed queries, this value is set to an array of English strings that describe the failure(s).

Rate Limits

An endpoint can limit how often it can be called. The documentation of each endpoint that has a limit gives that limit.

When a request is over the limit, the endpoint does not carry out the requested operation. The response is an error, as described above:

error_code is rate_limited.
error_messages contains one message. It gives the number of seconds until the limit allows the request again.
The Retry-After HTTP header contains the same number of seconds.

HTTP/1.1 200 OK
Retry-After: 42

{
  "success": false,
  "data": null,
  "error_code": "rate_limited",
  "error_messages": ["rate limit exceeded, please try again in 42 seconds"]
}

Using curl

Throughout this section, we include non-application specific examples of API calls.

curl can be a useful debugging tool. The following example demonstrates how to create a new Throttling Template using curl:

cat << 'EOT' > /tmp/body.json
{
  "throttling_template": {
    "name": "Example Throttling template",
    "rules": [
      {
        "domains": [
          "example-2.com",
          "example-1.com"
        ],
        "throttle_program": {
          "id": 1,
          "name": "this name doesn't exist"
        },
        "max_concurrent_connections": 2,
        "max_messages_per_hour": 0
      },
      {
        "domains": [
          "example-6.com",
          "example-7.com"
        ],
        "throttle_program": {
          "name": "test 2"
        },
        "max_concurrent_connections": 0,
        "max_messages_per_hour": 500
      }
    ],
    "default": {
      "max_concurrent_connections": 1,
      "max_messages_per_hour": 60
    }
  }
}

curl --user username:password -H "Content-Type: application/json" -X POST --data @/tmp/body.json https://example.com/ga/api/v3/eng/throttling_templates

See the Throttling Templates page for more details on the specific parameters being passed in the above example.