REST API Best Practices

Keep your API tokens secure and private

Your key or token is what is used to authenticate requests from your application to the Stackla REST API.

Stackla will validate the token each time a request is made and determine whether or not it is authorised and return the appropriate result.

As such it is vitally important that these tokens are kept secure and private at all times. Anyone with access to your token will have full control of your Stack via the REST API.

Only communicate via your secure back-end

Front-end API integrations such as Javascript and mobile applications by their nature are difficult to secure, especially Javascript as the code is fully available to every user.

To use the API in a front-end application, it must store and communicate your private token. Through this storage and communication process the token will be exposed to users of the application, potentially leading to unauthorised API requests by malicious parties.

Front-end integrations can also quickly exceed your API rate limit, as you often have little control over how many users you have or how many requests they make.

Stackla Developer Portal Guides section provides some direction as to how clients should consider approaching secure integrations utilising widgets and the Javascript API, for everything else ensure you only communicate securely using your back-end technology.

Authenticate using OAuth2

Clients who took advantage of Stackla’s REST API prior to October 2015 may have an API Key parameter generated for the purposes of authenticating calls made to the relevant endpoints by their third party applications.

This key is currently in the process of being phased out by Stackla and thus all new integrations should leverage an API token generated by the authorisation protocol OAuth2.
Generation of the 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.

Catch and handle response codes

Pay attention to which codes your requests generate. Catching, correctly interpreting and actioning responses returned by the Stackla REST API is important.

We expose API errors in two ways: standard HTTP response codes and human-readable messages in JSON format. Codes returned by the REST API can be found in the section titled Status and Error Codes. Ensure you handle unexpected errors (server connectivity, communication issues or statuses in the 5xx range) which could potentially cause problems with your integration.

Cache your API results

The Stackla REST API enforces a simple rate limit of 450 requests per 15 minute window by default.

Due to this limit, clients who are looking to utilise API results for public integrations are encouraged to cache results which allow appropriate scale to distribute results to many users rather than making requests on a per visit basis.

This approach not only helps reduce the chance of hitting the rate limit but will also help ensure faster responses for your application.

A guide for how to Cache REST API results for optimisation is available under the Guides section.

Avoid abuse from your application

To maintain a consistent and reliable experience for all our users Stackla’s API is constantly monitored for suspicious, spammy or abusive behaviour.

Not correctly observing your account’s rate limit, deliberately making recurring failed requests or exposing your API tokens to unauthorised parties maybe lead to additional throttling, access termination or legal action by Stackla.

Use the Software Developer Kit (SDK)

The Software Developer Kits for API integrations aim to assist in the development of applications integration with Stackla.

Clients looking to build integrations with PHP can take advantage of the Stackla PHP SDK.
SDK’s in other languages will be made available in the future.

Follow the terms of use

Finally, the Terms of Use define how to most prudently use the services and avoid being blocked.