UGC Techdocs
  • Introduction
  • Guides
    • Analytics
      • Tracking UGC on Adobe Analytics
      • Tracking Widget interactions with Google Analytics
    • Direct Uploader
      • How to add Custom Data to Direct Uploader
      • How to capture Custom Data on Direct Uploader
      • How to automatically tag data on Direct Uploader
      • How to Customize error messages on Direct Uploader
      • How to Track Direct Uploader form submissions with Google Analytics (Universal & GA 4)
    • Data Templates
      • Creating a Data Template
    • Rights via Registration
      • Capture Custom Data on Rights by Registration Form
      • Styling Rights via Registration Form
    • REST API
      • Caching REST API results for optimization
      • Posting content into Nosto via Tile API
      • Posting images into Nosto via Tile API
    • Onsite Widgets (2.0)
      • Blank Canvas
        • How to Use the Blank Canvas to Create a Twitter Count Widget
        • Creating an Auto-Scrolling Carousel using Blank Canvas
        • Creating Gallery Widget by Using the Blank Canvas Widget
        • Creating a simple Hover effect using Blank Canvas
        • Creating a Word Cloud using Blank Canvas
        • Creating Your Widget by Using the Blank Canvas
      • Bind your own Events
      • Creating a Grid Widget from Waterfall
      • Create a Q&A Widget using Data Templates
      • Displaying a Widget in a Mobile App
      • Dynamically Specify Products to Display in Widget
      • Dynamically specify what Tile to display in a Widget
      • How to add a title / subtitle to a widget
      • How to localize the load more button on widgets
      • How to overlay existing Google Map with the UGC Map Widget
      • Styling cross-sellers on Grid and Carousel Widgets
      • How to Load External JS and CSS into Widgets
      • Profiling Widget Performance
      • Re-targeting with Widgets and Facebook Pixel
      • Render Widget filters dynamically
      • Styling Carousel Widget
      • Styling Grid Widget
      • Styling Masonry Widget
      • Styling Waterfall Widget
      • Styling Widget Expanded Tile
      • Styling Widget Shopspots
      • Using Web Fonts in Widgets
    • Digital Screens
      • Customizing Carousel Event Screen
      • Customizing Mosaic Event Screen
      • Customizing Scrollwall Event Screen
      • Customizing the Mosaic Event Screen to Have 9 Even Tiles
    • Email
      • Adding Location to an Email Tile
      • Styling the Email Widget
    • Integrations
      • DoubleClick
        • UGC Ads with Nosto and Google DoubleClick
      • Zapier
        • Consuming UGC Webhooks via Zapier
      • Mailchimp
        • Bring Social Content into a Mailchimp Campaign
    • Webhooks
      • Trigger notifications when content is in the moderation queue
  • Widgets
  • API Docs
    • JavaScript API
      • Widgets
        • Introduction
        • API Reference for Content Widgets
        • API Reference for Blank Canvas
        • API Reference for Map Widget
      • Digital Screens
        • Introduction
        • API Reference
    • Content API
      • Reference
    • REST API
      • Reference
        • Filters API
        • Moderation Views API
        • Tags API
        • Terms API
        • Tiles API
        • Users API
        • Widgets API
        • Automation Rules API
        • REST API Reference Widgets style and config
      • Best Practices
    • Webhooks
  • Enterprise Tools
    • Automation Rules
      • Triggers
      • Actions
      • Samples
    • Data Templates
    • User Access Control (UAC)
    • Single Sign On (SSO)
    • Enterprise Admin User Interface (EAUI)
    • Zapier
  • Commerce Tools
    • Product Feeds
    • Widget Implementation
    • Reporting
    • Integrations
      • Google Tag Manager
      • Magento
      • SalesForce Commerce Cloud
      • Shopify
      • Shopify Add To Cart
        • Global Variant Mapping for Add to Cart
        • Customise Add to Cart Widget Experience
  • Analytics
    • Google Analytics 4
      • Getting Started
      • Widgets Events
      • E-commerce Events
      • Email Events
  • Terms of Use
Powered by GitBook
On this page
  • REST API Best Practices and Design Principles
  • Design for security
  • Keep your API tokens secure and private
  • Only communicate via your secure back-end
  • Authenticate using OAuth2
  • Design for speed
  • Cache your API results
  • Only cache what you need
  • Design for fault tolerance
  • Catch and handle response codes
  • Build resilient integrations
  • Design for integrity
  • Avoid abuse from your application
  • Follow the terms of use

Was this helpful?

  1. API Docs
  2. REST API

Best Practices

PreviousREST API Reference Widgets style and configNextWebhooks

Was this helpful?

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

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.

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

A guide for how to is available under the Guides section.

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

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

Guides
Cache REST API results for optimization
Status and Error Codes
Terms of Use