Getting Started with the Operator API
5 minute read
The Marketplacer GraphQL API allows developers to connect to a Marketplacer site to retrieve and modify data. Using this API it is possible to build a custom front-end to Marketplacer, to connect to a different eCommerce system, syndicate products, power a native mobile app and more.
This tutorial will cover the steps required to start querying data using the Marketplacer GraphQL API.
The first thing that is required to connect to the API is an API key.
If you prefer video to the written word, then the following video takes you through setting up the Marketplacer Operator API.
Getting your API key
Your site has API keys that are accessible under the Configuration menu in the administration portal.
In order to generate a key you’ll need to:
- Provide a description for the key - this helps when you have multiple keys used for different purposes
- Provide the name of the organization agreeing to the API License
- Accept that you have read the API License agreement
Please note that when you generate an API key, the key will only be shown once. If you forget the key, you will need to generate a new key.
We’ll make our first query to the API with the API key now.
Testing our API key
We can test that our API key works by doing a search for adverts in the site. The /graphql endpoint on your site is used for all GraphQL queries and mutations. We can use the Insomnia client to query for adverts.
To authenticate to the API, use an Authorization header:
If your site is currently password protected, you will not be able to supply a username/password AND an API key. If this is the case, set the username/password using basic authentication and send the API key using the MARKETPLACER-API-KEY header:
Here we did a very simple query which asks just for the advert’s title and the name of the taxon to which it is associated. A taxon is the category which is associated with an advert.
query
{
advertSearch(attributes: {keywordQuery: "Dog"}) {
adverts {
nodes {
title
}
}
}
}
We can add additional attributes to the query and retrieve more data:
query
{
advertSearch(attributes: {keywordQuery: "Dog"}) {
adverts {
nodes {
title
description
lowestPriceCents
}
}
}
}
Understanding Edges and Nodes
The Marketplacer GraphQL API follows the Relay Specification. This defines how data is returned when a one-to-many relationship is involved and is useful for paginating results. In this design, a node has attributes as well as connections to other nodes. A node represents one objects while an edge is the relationship between two nodes.
In the diagram above, Advert, Variant and Image are all nodes and the links between the nodes are all edges. When navigating through the data structure returned by the Marketplacer GraphQL API you will need to use the node and edge concepts to get to the data you’re interested in.
Queries and Mutations
In the previous examples we performed a Query against the GraphQL API. As its name suggests, a Query is a way to retrieve data from the API. Which attributes are returned is determined by the query you perform.
If you wish to update data, you need to use a Mutation instead. An example of a Mutation in the Marketplacer GraphQL API is orderCreate which (no surprises), creates an order for a given Product (we actually pass this mutation variant id as you’ll see in the example below).
IDs
The Node interface defined by Relay gives all objects a globally unique ID that can be used for looking up objects. This ID must be unique across all entities in the API - an advert cannot have the same ID as a Variant or an Order, for example. When given an ID, the API must be able to fetch the right object without knowing the type of object. This means that the IDs used in the GraphQL API are not the same IDs used in the admin & seller portals. In the case of both the Seller and Operator portals, the Ids we present there would be represented by the legacyId field on most GraphQL objects.
Example Mutation
In this section we will create a simple order, this will be a two-step process.
- First we must find a variant which can pass to
orderCreate. - We will then create the order using
orderCreate.
Finding a variant
A variant represents a purchasable variation of a product (aka Advert). For example, it may represent the small size of a t-shirt. Even if there are no size variations, an advert will always have a variant which is the item that must be added to the cart.
We can perform a search for adverts and request variants to be returned:
query
{
advertSearch(attributes: {keywordQuery: "Dog"}) {
adverts {
nodes {
title
variants {
nodes {
id
}
}
}
}
}
}
We get returned an advert including a variant.
{
"data": {
"advertSearch": {
"adverts": {
"edges": [
{
"node": {
"title": "Organic Dog Treats",
"variants": {
"edges": [
{
"node": {
"id": "VmFyaWFudC01NA=="
}
}
]
}
}
}
]
}
}
}
}
We now have the ID of a variant that we can use to create an order.
Creating an order with orderCreate
The orderCreate mutation lets us create an order by passing a valid variant id.
mutation {
orderCreate(
input: {
order: {
firstName: "Jane"
surname: "Doe"
phone: "+61405511111"
emailAddress: "janedoe@email.com"
termsAndConditionsAccepted: true
address: {
address: "South 23rd Street"
city: "San Jose"
country: { code: "US" }
postcode: "95116"
state: { name: "California" }
}
}
lineItems: [
{
variantId: "VmFyaWFudC01NA=="
quantity: 1
cost: { amount: 1000 }
}
]
}
) {
order {
id
status
}
errors {
field
messages
}
}
}
As well as the status, we retrieve the ID of the order (remember that IDs are globally unique) so we can refer to this order again when needed.
Further reading
The Marketplacer GraphQL API covers the queries and mutations you need to search, browse and display adverts and sellers as well as creating carts and orders. Read the full documentation to find out more, or interactively explore the schema with GraphQL Voyager.