Introduction
This reference is generated from the Topsort openapi specification and includes quite a few operations.
However, only two are required for a typical integration.
A typical integration
Provide your catalog via a product feed.
(Have vendors create campaigns).
Run auctions via the API or using our clients.
The details will depend on your marketplace and needs. A selection of examples is available here.
Use one of the analytics libraries to report events.
Available API’s
Typical integrations will use these APIs:
- Auctions: Runs auctions in your marketplace.
- Events: Collects data on auction results.
For advanced integrations you might want to look at:
- Audiences: Manage audiences.
- Campaigns: Manage campaigns.
- Catalog: Manage products, categories and vendors.
- Billing: Manage vendor balances.
- Reporting: Read reports on marketplace, campaign or product performance.
- Invitations: Invite vendors to your marketplace.
URLs and redirects
To minimize the impact of auctions on your app’s performance, there is no redirect from URLs with a trailing slash (/
). This is to avoid an extra round trip before auction winners are returned.
For example, when you want to run an auction, use /v2/auctions
, not /v2/auctions/
.
Using an URL with a trailing slash will result in a 404 Not Found
error.
API Status
You can monitor and check API Status here.
Rate Limits
Topsort enforces rate limits on some of the endpoints to ensure that the quality of service is maintained for all users. The rate limits are different for the production and sandbox environments and are as follows:
Environment | Endpoint | Rate Limit |
---|---|---|
Sandbox | Catalog API | 4 rps |
Sandbox | Other Advanced APIs | 5 requests every 2 seconds |
Sandbox | Auctions and Events | No rate limit |
Production | Catalog API | 10 rps |
Production | Other Advanced APIs | 45 requests every 2 seconds |
Production | Auctions and Events | No rate limit |
Rate limit headers
Use these headers to navigate rate limits and when you can make another request:
X-RateLimit-Limit
- total number of requests allowed for the time periodX-RateLimit-Remaining
- remaining number of requests for the time periodX-RateLimit-Reset
- when you can make another request
How to handle rate limits
When you exceed the rate limit, you will receive a 429 Too Many Requests
response. To handle this, you can implement a retry mechanism with an exponential backoff strategy. This will help you to avoid hitting the rate limit again.
Here is an example of how you can implement this in Typescript:
/**
* Wraps `fetch()` with a retry function that respects retry limits from the API
*
* @param {string|URL} url
* @param {RequestInit} request
* @param {number} retries = 1
* @returns {Promise<Response>}
*/
async function fetchWithRetry(url, request, retries = 1) {
const response = await fetch(url, request);
if (!response.ok) {
if (response.status === 429) {
// Handle rate limit
const ms = response.headers.get("X-RateLimit-Reset");
await new Promise((resolve) => setTimeout(resolve, ms));
return fetchWithRetry(url, request, retries + 1);
}
throw new Error(`Failed to upload: ${response.status} ${await response.text()}`);
}
}
OpenAPI Specification
The OpenAPI specification is available as a JSON file here.