Operator API Collections

Intro

The Marketplacer Operator API collections have been provided to get developers new to Markerplacer up and running quickly with the Operator API by providing a curated set of the most commonly used queries and mutations. Collections have been provided for both Postman and Insomnia.

Downloads

When developing against the Operator API, you can use a number of different API Test clients to make your life easier, for example:

• Postman
• Insomnia
• Altair
• GraphiQL

We have created API collections for both Postman and Insomnia, which can be downloaded below.

• Download the Postman Collection for the Operator API here.
• Download the Insomnia Collection for the Operator API here.

Postman

Postman is a tool for developing and testing API integrations. It provides an interface for exploring APIs and executing requests against them. You can download our Postman Collection here.

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

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

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

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

Insomnia

Insomnia is an alternative API client that can be used to run GraphQL queries and mutations in much the same way as Postman. Insomnia is particularly good at working with GraphQL as it ingests the GraphQL schema, enabling it to provide tool-tips, auto-code completion and present the in-line API documentation. Our Insomnia Collection can be downloaded here

To import, click the “Create” button on the Insomnia Dashboard, and select “(Import From) File”:

Select the Marketplacer GraphQL API.insomnia_collection.json file you downloaded in the previous step, and click ok. You should see the confirmation once the file has imported:

Select the “Marketplacer Collection”

We now need to configure the base environment to:

• Point to your Marketplacer GraphQL API endpoint
• Use a your API Key
• [Optional] Configure credentials to connect to a staging environment

To do so, click the Environment drop down, then select Manage Environments:

As a minimum, you’ll need to provide values for:

• base_url
• graphql_api_key

If you’re using a staging environment, then you should provide values for:

• basic_auth_username
• basic_auth_password

An example of what your base environment config should look like is shown below (don’t forget to click “Done” after making any changes):

You should now be able to start using the Insomnia Collection.

Collections Overview

While the queries and mutations in the collection are quite self-explanatory, we have provided some additional detail on what each does along with a few other hints and tips.

It is also worth remembering that the queries and mutations provided in the collection are just a sample of what the GraphQL API can provide. For the full documentation, please refer to:

• Full Documentation
• GraphQL Voyager An interactive visualization of our schema

Both of the above are based off the same GraphQL Schema, they just represent the information in different ways.

Sellers

We have 2, (very similar!), example queries in the collection that allow you to return all, or some of the Sellers on the Marketplace.

• Get all Sellers
• Get all Sellers based on Business Name

It’s worth noting that you can search for Sellers based on more than just businessName, e.g. you can filter by:

• updatedSince
• State
• Distance (Geographic radius in which to look for Sellers, e.g. within 10KM)

(These are just a sample of some of the filter criteria that can be used.)

Why would I use these?

You would use these queries to allow you to obtain the SellerId, which you can then use as part of your other queries, e.g. advertSearch (by SellerId), to obtain all Adverts for a given Seller (or Sellers)

Adverts

Adverts represent the Products or Services that a Seller may sell on a Marketplace. Going a little further an Advert, (e.g. for a Ski Jacket), may have multiple Variants, e.g.:

• Small / White
• Small / Black
• Large / White
• Large /Black

(You get the picture!)

The queries in this section all relate to how you can query the Adverts on the Marketplace, and further still, retrieve “child” objects of the Advert, e.g. the “Variants” of the Advert. We have provided the following 3 example queries:

• Get all Adverts by Keyword
• Get all Adverts for a Seller (using the “SellerId")
• Get all Adverts “updated since”

Looking more closely at the collection, you’ll notice we actually make use of 2 different “queries”:

• advertSearch
• allAdverts

We have summarized their differences below, and why you’d use 1 over another

Order

The final items in our collection relate to an Order, an Order represents the purchase of one or more Variants, (aka Line Items), across 1 or more Sellers. We have 1 mutation and 1 query in our collection:

• Create a new Order
• Retrieve an Order

Taking a closer look at the orderCreate mutation, you’ll note that you can add multiple Variants to the Order in the LineItems section:

lineItems: 
[
  {             
    variantId: "VmFyaWFudC0yODE="
    quantity: 1
    totalCents: 22500
    postageCents: 1000 
  },
  {             
    variantId: "VmFyaWFcbC0yEDE="
    quantity: 2
    totalCents: 50000
    postageCents: 1000       
  }
]

If these 2 Variants relate to 2 different Adverts, from 2 different Sellers, then 2 Separate Invoices will be created for the Order. (An Invoice is part of an Order that is handled by a particular Seller).

This relationship is shown below:

It’s also worth noting that separate invoices will be created for the same seller if different delivery methods have been chosen for Line Items, e.g.:

• Line Item 1 – Delivery Method = “Deliver”
• Line Item 2 – Delivery Method = “Click and Collect”

This will result in 2 separate Invoices even if the Line Items have been sold by the 1 Seller.

Creating Invoices Manually

In the example above we have shown how you can add Line Items (Variants) directly on the Order, (and that Invoices will be auto-generated), you can however take an alternative approach and create an Order with Invoices and then add Line items to the Invoice. So, we in effect we have 2 approaches:

• Create Line Items directly on the Order as per the example, and Invoices will be created for you.
• Create Invoices “manually” on the Order and add Line Items to the Invoices

Creating orders is described on more detail here.

Order Query

Using the Order query, you can return the child objects of the Order, including:

• Invoices
• Line Items
• Shipments