Overview
5 minute read
IMPORTANT
Sellers building integrations into Marketplacer should only use the current GraphQL-based Seller API, and not this (REST-based) API.
All future developments, including new features will be added to the the GraphQL-based Seller API only, more details on this API can be found here
This describes the resources that make up the official Marketplacer API V2.
Issues
If you encounter any issues with using this API, please contact our support team here with:
- an example of what request you’re making
- What headers + body are being returned from the server
- What you expect to happen
JSON API
This API complies with the jsonapi.org specification. Please consult its documentation to learn about it if you have not done so already.
Evolvability and Versioning
This API will evolve over time and new fields will be added to responses as new features are implemented. Ensure that any software parsing API responses is able to handle new fields being added at any time.
If it is necessary to remove or change the meaning or data-type of a field, we will inform customers of a change and continue supporting the old behavior until all clients have had a chance to update.
If you wish to receive these notifications, please let us know here, or you can view the change log here.
HTML Sanitization
We do not currently perform any type of HTML sanitization on resource attributes that could contain HTML or Script fragments. It is the responsibility of the consuming endpoint to perform such checks.
Content Type
API clients must supply a Content-Type
header of application/vnd.api+json
when sending request data:
$ curl -H "Content-Type: application/vnd.api+json" -d "{ ... }" -X POST https://bestfriendbazaar.com/api/v2/client/adverts
Pagination
Some resources may be paginated. Each paginated collection defaults to returning 50 resources at a time, with a maximum limit of 1100 if desired. A paginated resource will always contain a links
key on the top-level which contains first
, next
and last
keys:
{
links: {
"first": "[route]?page[number]=1&page[size]=50",
"next": "[route]?page[number]=2&page[size]=50",
"last": "[route]?page[number]=2&page[size]=50"
}
}
The “first” link returned here is the link to the first page of this resource. The “next” link is the next page of this resource, and the “last” link indicates the last page of results that will show results.
For instance, to paginate through the Variants endpoint, you can make requests as so:
GET https://bestfriendbazaar.com/api/v2/client/variants?page[number]=1
GET https://bestfriendbazaar.com/api/v2/client/variants?page[number]=2
...
GET https://bestfriendbazaar.com/api/v2/client/variants?page[number]=n
You can also change the number of items returned in one request by using the page[size]
parameter. This example will only show 10 items at a time:
GET https://bestfriendbazaar.com/api/v2/client/variants?page[size]=10
A maximum value of 500 can be specified.
Authentication
To authenticate to the API, use an Authorization
header:
$ curl -H "Authorization: Bearer api_key" https://bestfriendbazaar.com/api/v2/client/adverts
If your site is protected by basic authentication, that will conflict with the Bearer
method. In that case, send your API key using MARKETPLACER-API-KEY
:
$ curl -u username:password -H "MARKETPLACER-API-KEY: api_key" https://bestfriendbazaar.com/api/v2/client/adverts
Information on how to create your api_key
can be found in Getting Started
API Key Rotation
For more information on our API Key Rotation recommendations, please refer to this playbook.
Rate Limiting
We reserve the right to rate limit requests when call volume or load are too high. Rate limits may be expressed via the following HTTP response codes:
- 429 Too Many Requests response
- 503 Service Unavailable response.
These responses may contain a retry-after header which can be a number of seconds or a date.
If no retry-after header is provided then the default retry after value is 60s.
Retrying Requests
There may be occasions where you will need to retry the API request you made to Marketplacer as the original attempt may have failed. The reason an API call may fail will fall into 1 of 2 general error classes:
- Transient error conditions are those scenarios where retrying the same request again at a later point in time would likely result in a successful outcome. Examples of this type of error would be:
- Temporary network unavailability
- Rate limits have been hit
- Some other reason related to platform availability
- Non-transient error conditions are those scenarios where retrying the same request again at a later point in time would continue to result in an unsuccessful outcome. Examples of this type of error are:
- Malformed payload body
- Incorrect authentication credentials
Transient Vs Non-transient errors
Calls that fail due to non-transient errors are generally considered harder to retry, as you would usually need to change something about the original call in order for it to succeed.
With calls that fail for transient reasons, you just need retry that same call at a future point in time. An example of this type of retry is discussed below.
Retry Headers
One example of a transient error class that you may encounter when making API calls is to receive a HTTP 503 error response. This response will be accompanied by a rety-after
header, an example of which is shown below:
retry-after: 30
The value of this header is the minimum time in seconds that you should wait before attempting to make another (retry) request.
Retry Playbook
For a more in depth discussion on Retrying API calls, please take a look at the following playbook.Postman Collection
We have provided a Postman collection of the most used API calls, you can read more about the collection here.