REST

Overview

In order to interface with some of the core functionality, Stackla has exposed specific resources via a REST API. This gives developers a great deal of flexibility when integrating Stackla and opens up the doors to very exciting activations. While the JavaScript API deals mainly with the display of content, the REST API provides a way for the backend to interface directly with the Stack configuration, data and functionality. Check out our guides to see a sample of use cases.

Customers on the Platform licence are able to activate API as a Stackla Plugin using the Plugins area of the Admin Portal.

Rate Limits

The API enforces a simple rate limit of 450 requests per 15 minute (900 second) time window per client. This includes all types of requests, namely GET, POST, PUT and DELETE. Requests made in excess will be blocked and return a HTTP 403 status (Rate Limit Exceeded). Clients who exceed this rate limit constantly may be blocked by API access revokation, IP address, or otherwise (see Terms of Use).

To measure current use and limits you can either refer to your Stack Admin’s API Console, or by inspecting the response headers of every request:

  • X-API-Remaining-Requests-Reset – The time (in seconds) remaining until the Rate Limit Time Window resets
  • X-API-Remaining-Requests – The number of requests available in the current Rate Limit Time Window
Note about measuring rate usage

There are up to 2 additional request reserved in the rate limit time window for querying a future (i.e. to be implemented) API resource. The data returned in the counter will reflect this.

Most uses of the API will easiliy fit inside of this rate limit by utilising server-side caching mechanisms. For more information about this, please reach out to our support team. If you believe that you need to increase your rate limit allowance, please contact your sales representative.

Authentication and Authorisation

The Stackla REST API supports basic authentication and authorisation as an OAuth2 provider.

Each use of the Stackla API requires a valid client token, provided by the access_token URL query parameter or the x-access-token header parameter. Each client token will perform actions on behalf of the user that has authorised its use.

Generating a client token can be done either in the Admin Portal by configuring the Stackla API Plugin (as each admin, individually) or by implementing the authorisation protocol of the Stackla API application yourself. You will most likely perform the former, however if you need to implement yourself, our SDK may be of use to get you started.

Note that Stacks created prior to October 2015 may also have an API Key parameter generated. The key is most often a random hash and will be appended to REST requests as a URL query parameter api_key. As of 2015, the Stackla API is supporting OAuth2 as the main method and will be deprecating the API key method over time. Please contact us if you have any questions or concerns.

Content Type and Accept Headers

All POST requests to the API must be made with Content-Type set to “multipart/form-data”. At this point the API will not interpret any other Content-Types. Other request types should specify pointers or operators in URL-encoded queries.

Requests can be made to respond in both JSON (“application/json”) or XML (“application/xml”) format. To modify the accepted type, you may specify it in either the HTTP header as the Accept header (e.g. “Accept: application/xml”). You can also specify it as the resource extension. For example, to request Filter ID 123 to be returned as XML format, your request may resemble:

https://api.stackla.com/api/filters/123.xml?access_token=1234abcd5678efgh&stack=mystack

Similarly, change XML above to JSON to have it respond in JSON format.

If no type is specified, JSON is assumed and preferred over XML. Please note that the XML format is a limited implementation and provided on an “as-is” basis and may only be suitable for some implementations.

Response Format

All responses will contain a specific HTTP status and wrap the payload in data and errors branches/fields. Data may be an object, or an array of objects depending on the request. Errors will either be an empty array, or an array of error codes and messages.

Example of a valid response, with no errors (formatted for clarity)
{
    "data": {
        "id": "1234",
        "stack_id": "9999",
        "name": "Latest",
        ...
    },
    "errors": []
}
Example of an error (formatted for clarity)

Note: message is a general description of the reason for the error, it sometimes can be an object.

Note: error_code and message_id are 2 new fields that contain unique values for different types of errors.
Due to the amount of work, this is still in progress. If an error has not been defined, error_code returns 0.

{
    "data": [],
    "errors": [
        {
            "message": "Invalid resource specified or resource not found",
            "code": 404,
            "error_code": 1080404,
            "message_id": "term:not_found"
        }
    ]
}

Result Counters

Some queries (such as Tag keyword searching/matching) also return counters based on totals and how many the query matched. For example, if you have a total of 200 tags, a search for the keyword “%hello%” yields 150 results, you should see something like the following.

Note: These numbers are not necessarily related to the results returned and their counters.

{
    "data": [
        ...
    ],
    "errors": [],
    "count": {
        "results_total": "150",
        "total": "200"
    }
}

Pagination

Results sets can be navigated in sets of pages of a finite limit. The limit of each page can be set via the limit parameter, and can range between 1 and 100 results. Both the page and limit parameters can be set as a URL query, such as:

https://api.stackla.com/api/filters.json?access_token=1234abcd5678efgh&stack=mystack&limit=10&page=3

In this example (i.e. page 3 and page limit to 10), the request would yield results 21 to 30.

Status and Error Codes

Every request to the interface will result in one of the following codes. You may adjust your application strategy to deal with the HTTP responses (e.g. “back-off” when rate limit is exceeded, trigger alert when a 400 or 401 is returned, etc.).

Status HTTP Code Description
API_STATUS_OK 200 OK: All is good, request received, processed successfully and data returned.
API_STATUS_BAD_REQUEST 400 Bad request: The request could not be understood
API_STATUS_UNAUTHORIZED 401 Unauthorized: Authentication credentials invalid or not authorised to access resource
API_STATUS_RATE_LIMIT_EXCEEDED 403 Rate limit exceeded: Too many requests in the current time window
API_STATUS_INVALID_RESOURCE 404 Invalid resource: Invalid resource specified or resource not found
API_STATUS_SERVER_ERROR 500 Server error: An error on the server prohibited a successful response; please contact support

There may be occasions where other error codes (such as 5xx status) are returned. In this case please contact Stackla support to investigate.

API Specification

Please see the REST API Reference page for the resources and fields you can use in your applications.
To have a play, head to the API Console in your Stack Admin