.png%3Falt%3Dmedia%26token%3D6deff902-b475-4b95-bffc-b313f43260b5)
.png%3Falt%3Dmedia%26token%3D6deff902-b475-4b95-bffc-b313f43260b5)
Best Practices
This document outlines Visual UGC's best practices for using its REST API and serves as a high-level guide on how third-party integrations should be designed.
Your key or token is what is used to authenticate requests from your application to the Visual UGC REST API.
Visual UGC 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.
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.
Visual UGC 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.
Clients who took advantage of Visual UGC’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 Visual UGC 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 Visual UGC API Plugin (as each admin, individually) or by implementing the authorisation protocol of the Visual UGC API application yourself.
The Visual UGC 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.
By default, when you request a tile via Visual UGC’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 Visual UGC 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.
Pay attention to the response codes your requests generate. Catching, correctly interpreting and handling responses returned by the Visual UGC 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.
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 Visual UGC'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.
To maintain a consistent and reliable experience for all our users Visual UGC’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.
Last modified 14d ago