Overview

What is the Operator API

The Marketplacer Operator API is predominantly used to build integrations into existing eCommerce platforms where products hosted on Markerplacer are surfaced for sale on the eCommerce frontend.

The range of operations that you can perform with this API include but are not limited to the following domains:

• Product (aka Adverts)
• Orders
• Categorization (aka Taxonomy)
• Shipping
• Remittances

GraphQL

This API complies with the graphql specification. If you’ve not worked with GraphQL before, then we strongly recommend taking a look at these docs as they give you a good grounding on the general concepts you’ll need if you want to get the most out of working with the API.

This video also gives a brief introduction to general GraphQL concepts:

Additionally, while you work with our GraphQL API, you may also find the following resources useful:

• Full Documentation A text-based representation of the GraphQL schema
• GraphQL Voyager An interactive visualization of the GraphQL schema
• Playbooks Scenario-based examples covering end to end concepts
• Video A wide range of videos coring what can be done with GraphQL
• Code Code examples covering a number of core scenarios

Relay Specification

In addition to implementing the GraphQL specification, this API also follows the Relay Specification. This is a set of guidelines and conventions developed by Facebook for building GraphQL APIs in a consistent and efficient way.

It provides an opinionated view on things such as:

• The structure of GraphQL queries & mutations
• Interfaces for object types
• Pagination & Caching

Page Sizes

Paging result sets should be employed as a matter of best practice irrespective of the expected result set size.

A maximum page size of 500 is recommended for all GraphQL APIs.

This article explains how to use pagination with GraphQL queries.

API Collections

We have provided API collections for both Postman and Insomnia to get you started, please visit the Operator API Collections page to download and get started.

HTML Sanitization

We do not currently perform any type of HTML sanitization on object fields 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/json when sending request data:

Authentication

To authenticate to the API, use an Authorization header to pass your API Key:

If your Marketplacer instance is password protected via Basic Authentication, you will not be able to supply an API key and a username/password using an Authorization header.

In this case, set the username/password using the Authorization header (select the Basic Authentication scheme) and set the API key using the MARKETPLACER-API-KEY header:

Information on how to get 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.

Issues

If you encounter any issues with using this API, please contact our support team here 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