Best Practices

REST API Best Practices and Design Principles

This document outlines Nosto's UGC 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 Nosto's UGC REST API.

Visual UGC will validate the token each time a request is made determine whether it is authorized 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 unauthorized 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.

Nosto's UGC Techdocs Guides section provides some direction as to how clients should consider approaching secure integrations utilizing 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 Nosto's UGC REST API before October 2015 may have an API Key parameter generated for 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 authorization 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 authorization protocol of the Visual UGC API application yourself.

Design for speed

Cache your API results

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 utilize API results for public integrations should cache data in their back-end to allow the 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 optimization is available under the Guides section.

Only cache what you need

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

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 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) that could potentially cause problems with your integration, not doing so could have many knock-on effects.

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 uptimes, 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 it's fulfilling, but the impact of the reliance on third-party services like Visual UGC's REST API should be analyzed 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 slowdown 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 Nosto's UGC API is constantly monitored for suspicious, spammy, or abusive behavior.

Not correctly observing your account’s rate limit, deliberately making recurring failed requests, or exposing your API tokens to unauthorized parties may 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.