.png%3Falt%3Dmedia%26token%3D6deff902-b475-4b95-bffc-b313f43260b5)
.png%3Falt%3Dmedia%26token%3D6deff902-b475-4b95-bffc-b313f43260b5)
Reference
In order to interface with some core functionality, Visual UGC has exposed specific resources via a REST API. This gives developers a great deal of flexibility when integrating Visual UGC and opens up the doors to very exciting activations. While the JavaScript API deals mainly with the display of content, the REST API provides a way for the backend to interface directly with the Stack configuration, data and functionality. Check out our guides to see a sample of use cases.
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.
Key Features
- 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.
Designed for
- 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.
The API enforces a simple rate limit of 450 requests per 15 minute (900 second) time window per client. This includes all types of requests, namely GET, POST, PUT and DELETE. Requests made in excess will be blocked and return an HTTP 403 status (Rate Limit Exceeded). Clients who exceed this rate limit constantly may be blocked by API access revokation, IP address, or otherwise (see Terms of Use).
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:
https://api.stackla.com/api/filters/123**.xml**?access_token=1234abcd5678efgh&stack=mystack
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)
{
"data": {
"id": "1234",
"stack_id": "9999",
"name": "Latest",
...
},
"errors": []
}
Example of an error (formatted for clarity)
Note:
message is a general description of the reason for the error, it sometimes can be an object.Note:
error_code and message_id are 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, error_code returns 0.{
"data": [],
"errors": [
{
"message": "Invalid resource specified or resource not found",
"code": 404,
"error_code": 1080404,
"message_id": "term: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.
{
"data": [
...
],
"errors": [],
"count": {
"results_total": "150",
"total": "200"
}
}
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:
https://api.stackla.com/api/filters.json?access_token=1234abcd5678efgh&stack=mystack**&limit=10&page=3**
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.).
Status | HTTP Code | Description |
|---|---|---|
API_STATUS_OK | 200 | OK: All is good, request received, processed successfully and data returned. |
API_STATUS_BAD_REQUEST | 400 | Bad request: The request could not be understood |
API_STATUS_UNAUTHORIZED | 401 | Unauthorized: Authentication credentials invalid or not authorised to access resource |
API_STATUS_RESTRICTED | 403 | Forbidden: Access to resource is restricted |
API_STATUS_RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded: Too many requests in the current time window |
API_STATUS_INVALID_RESOURCE | 404 | Invalid resource: Invalid resource specified or resource not found |
API_STATUS_SERVER_ERROR | 500 | Application error: An error within the application has prohibited a successful response; please contact support |
(An empty status will be returned) | 503 | Network error: An error within the network prohibited a successful response; please contact support |
(An empty status will be returned) | 504 | Network error: An error within the network prohibited a successful response; please contact support |
There may be occasions where other error codes (such as 5xx status) are returned. In this case please contact Visual UGC support to investigate.
Please see the REST API Reference page for the resources and fields you can use in your applications. To have a play, head to the API Console in your Stack Admin
Last modified 2mo ago