Overview

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 suppport team at support@marketplacer.com with:

  1. an example of what request you’re making
  2. What headers + body are being returned from the server
  3. 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 behaviour until all clients have had a chance to update.

If you wish to receive these notifications, please let us know at support@marketplacer.com

Rate Limits

There is a rate limit of 50 transactions per second on all our REST endpoints.

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 is limited to 100 resources at a time. 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]=100",
    "next": "[route]?page[number]=2&page[size]=100",
    "last": "[route]?page[number]=2&page[size]=100"
  }
}

The “first” link returned here is the link to the first page of this reosurce. 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

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

Postman Collection

Postman is a tool for developing and testing API integrations. It provides an interface for exploring APIs and executing requests against them. A postman collection is a document describing a series of API requests that can be imported into Postman to speed up this process. We have published a Postman collection for the Marketplacer v2 API. It contains example requests for a number of the API endpoints.

To import into Postman, download the .json file and go to the import menu in Postman:

Postman Import

Choose the .json file you downloaded and confirm that you wish to import it:

Postman Confirmation

Edit the collection to fill in the variables required to access your site (see the Postman documentation for more information)):

Postman Variable Configuration

You will now see a series of requests in Postman which you can study and execute:

Postman Request List