REST API Best Practices and Design Principles

This document outlines Stackla’s best practices for using its REST API and serves as a high-level guide on how third-party integrations should be designed.

Design for security

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 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.

Design for speed

Cache your API results

The Stackla REST API is calibrated for returning fresh, raw data and therefore enforces a default rate limit of 450 requests per 15 minute window.

Clients who are looking to utilise API results for public integrations should cache data in their back-end to allow appropriate scale to distribute data to many users rather than making requests on a per-visit basis.

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

Only cache what you need

By default, when you request a tile via Stackla’s REST API you get a document containing a lot of verbose details, most of which are rarely needed outside servicing a content management system.

If you’re building an integration for display purposes, be specific around the information you require for the display and optimize your storage by discarding data you don’t need. Keeping the cached Stackla data lean can greatly speed up the storage, processing and delivery requirements on your end, this will lead to a better user experience on your front-end application.

Design for fault tolerance

Catch and handle response codes

Pay attention to the response codes your requests generate. Catching, correctly interpreting and handling 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, not doing so could have many knock-on affects.

Build resilient integrations

Any issue occurring with a third-party (an API or otherwise) should cause minimal knock-on issues to your website, application or users. It is the nature of technology that things will sometimes fail, it’s best to be prepared.

The scaling, delivery speed, back-end up-times and Service-level agreement (SLA) requirements should all be considered when designing a system powering a website or mobile app. Each application is unique to the business requirements its fulfilling, but the impact of the reliance on a third-party services like Stackla’s REST API should be analysed and accounted for when you’re designing your integration.

Third-party reliance should be avoided and anything outside the purview and control of your development team should be loosely coupled from your core system. Ensure that any third-party slow down or content delivery issues have minimal impact on your system. Protect yourself by designing for speed and stability; decouple points of failure and, utilize internally managed systems to store and deliver data to your front-end.

Design for integrity

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.

Follow the terms of use

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