Customers on the Platform licence are able to activate API as a Visual UGC Plugin using the Plugins area of the Admin Portal.
Visual UGC's REST API is the key to the integration point of many backend client applications, used to manage all areas of the Visual UGC product, enrich data stores and ensure content taxonomy is updated in real time.
- Rate limited.
- Prioritises real-time uncached data results.
- Powerful control set to match core Visual UGC functionality.
- Secure access via OAuth tokens.
- Confirms to REST structure and HTTP messaging.
- Restricts browser based requests.
- Powering custom B2B applications.
- Integrating with CRMs and BI tooling.
- Managing real-time data via external management tools.
- Enriching external data stores.
- Synching external content taxonomy.
To measure current use and limits, you can either refer to your Stack Admin's API Console, or by inspecting the response headers of every request:
- X-API-Remaining-Requests-Reset - The time (in seconds) remaining until the Rate Limit Time Window resets
- X-API-Remaining-Requests - The number of requests available in the current Rate Limit Time Window
Note about measuring rate usage
There are up to 2 additional request reserved in the rate limit time window for querying a future (i.e. to be implemented) API resource. The data returned in the header will reflect this.
Most uses of the API will easiliy fit inside this rate limit by utilising server-side caching mechanisms. For more information about this, please reach out to our support team. If you believe that you need to increase your rate limit allowance, please contact your sales representative.
The Visual UGC REST API supports basic authentication and authorisation as an OAuth2 provider.
Each use of the Visual UGC API requires a valid client token, provided by the access_token URL query parameter or the x-access-token header parameter. Each client token will perform actions on behalf of the user that has authorised its use.
Generating a 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. You will most likely perform the former, however if you need to implement yourself, our SDK may be of use to get you started.
Note that Stacks created prior to October 2015 may also have an API Key parameter generated. The key is most often a random hash and will be appended to REST requests as a URL query parameter api_key. As of 2015, the Visual UGC API is supporting OAuth2 as the main method and will be deprecating the API key method over time. Please contact us if you have any questions or concerns.
All POST requests to the API must be made with Content-Type set to "multipart/form-data". At this point, the API will not interpret any other Content-Types. Other request types should specify pointers or operators in URL-encoded queries.
Requests can be made to respond in both JSON ("application/json") or XML ("application/xml") format. To modify the accepted type, you may specify it in either the HTTP header as the Accept header (e.g. "Accept: application/xml"). You can also specify it as the resource extension. For example, to request Filter ID 123 to be returned as XML format, your request may resemble:
Similarly, change XML above to JSON to have it respond in JSON format.
If no type is specified, JSON is assumed and preferred over XML. Please note that the XML format is a limited implementation and provided on an "as-is" basis, and may only be suitable for some implementations.
All responses will contain a specific HTTP status and wrap the payload in data and errors branches/fields. Data may be an object, or an array of objects, depending on the request. Errors will either be an empty array, or an array of error codes and messages.
Example of a valid response, with no errors (formatted for clarity)
Example of an error (formatted for clarity)
messageis a general description of the reason for the error, it sometimes can be an object.
message_idare 2 new fields that contain unique values for different types of errors. Due to the amount of work, this is still in progress. If an error has not been defined,
"message": "Invalid resource specified or resource not found",
Some queries (such as Tag keyword searching/matching) also return counters based on totals and how many the query matched. For example, if you have a total of 200 tags, a search for the keyword "%hello%" yields 150 results, you should see something like the following.
Note: These numbers are not necessarily related to the results returned and their counters.
Results sets can be navigated in sets of pages of a finite limit. The limit of each page can be set via the limit parameter, and can range between 1 and 100 results. Both the page and limit parameters can be set as a URL query, such as:
In this example (i.e. page 3 and page limit to 10), the request would yield results 21 to 30.
Every request to the interface will result in one of the following codes. You may adjust your application strategy to deal with the HTTP responses (e.g. "back-off" when rate limit is exceeded, trigger alert when a 400 or 401 is returned, etc.).