2. Endpoint Mapping
12 minute read
Introduction
In this section we map the existing REST API endpoints to their GraphQL equivalents, we do this by grouping the REST endpoints as follows:
- Adverts (Products)
- Brands
- Images
- Documents
- Inventory (multi-store)
- Invoices (Orders)
- Shipments
- Shipping Profiles
- Taxons
- Multi-store memberships
- Variants
Best fit
While we provide the relevant GraphQL mappings to each REST endpoint, as you explore the GraphQL API you may find alternate ways to solve for your use-case. The suggestions we provide here are the general “best-fit”, but of course you can use whatever GraphQL query or mutation best suits your needs.
The reader should also be aware that this playbook only covers the mapping of existing REST functionality to GraphQL. The GraphQL API contains functionality not resident in the REST equivalent, (e.g. Refunding), so these endpoint types (unique to GraphQL) are not covered in this playbook.
We are only mapping what is in REST to the equivalent in GraphQL.
Adverts
Use-case | REST | GraphQL |
---|---|---|
List adverts without filters | GET /api/v2/client/adverts | allAdverts - Example |
List adverts with filters | GET /api/v2/client/adverts?sku=VALUE | advertsWhere - Example |
Get a single advert | GET /api/v2/client/adverts/1 | node (advert) - Example |
Get a single advert with additional resources | GET /api/v2/client/adverts/1?include=variants,shipping_parcel | node (advert) - Example |
Create an advert | POST /api/v2/client/adverts | advertUpsert - Example |
Update an advert | PUT /api/v2/client/adverts/1 | advertUpsert - Example |
Resubmit a rejected advert for vetting | PUT /api/v2/client/adverts/1/resubmit_for_vetting | advertVettingResubmit - Example |
Deleting an advert | DELETE /api/v2/client/adverts/1 | advertDelete - Example |
Brands
Use-case | REST | GraphQL |
---|---|---|
Listing brands | GET /api/v2/brands | brands - Example |
Search for a brand | GET /api/v2/brands/search?name=Giant | brandSearch - Example |
Images
Use-case | REST | GraphQL |
---|---|---|
List an adverts images | GET /api/v2/client/adverts/1/images | node (advert) - Example |
List a variants images | GET /api/v2/client/variants/1/images | node (variant) - Example |
Showing a single image | GET /api/v2/client/adverts/1/images/1 | node (image) - Example |
Adding an image to an advert | POST /api/v2/client/adverts/1/images | advertUpsert - Example |
Adding an image to a variant | POST /api/v2/client/variants/1/images | advertUpsert - Example |
Updating an adverts image | PUT /api/v2/client/adverts/1/images/1 | advertUpsert - Example |
Updating a variants image | PUT /api/v2/client/variants/1/images/1 | variantUpdate - Example |
Deleting an adverts image | DELETE /api/v2/client/adverts/1/images/1 | advertUpsert - Example |
Deleting a variants image | DELETE /api/v2/client/variants/1/images/1 | variantUpdate - Example |
Documents
Use-case | REST | GraphQL |
---|---|---|
Listing an adverts documents | GET /api/v2/client/adverts/1/documents | node (advert) - Example |
Showing a single document | GET /api/v2/client/adverts/1/documents/1 | node (document) - Example |
Adding a document | POST /api/v2/client/adverts/1/documents | advertUpsert - Example |
Updating a document | PUT /api/v2/client/adverts/1/documents/1 | advertUpsert - Example |
Deleting a document | DELETE /api/v2/client/adverts/1/documents/1 | advertUpsert - Example |
Inventory (multi-store)
Use-case | REST | GraphQL |
---|---|---|
Listing a variants inventory | GET /api/v2/client/variants/1/inventories | node (variant) Example |
Updating a variants inventory | PUT /api/v2/client/variants/1/inventories | Not currently supported |
Deleting an inventory record | DELETE /api/v2/client/variants/1/inventories/1 | Not currently supported |
Invoices (Orders)
Use-case | REST | GraphQL |
---|---|---|
Listing invoices no filters | GET /api/v2/client/invoices | invoices Example |
Listing invoices with filters | GET /api/v2/client/invoices?updated_since=2015-11-10T00:00:00Z&status=sent | invoices Example |
Listing invoices with additional resources | GET /api/v2/client/invoices?include=line_items,customer | invoices Example |
Show an individual invoice | GET /api/v2/client/invoices/1 | node (invoice) Example |
Sending an invoice | PUT /api/v2/client/invoices/1/sent | shipmentCreate Example |
Readying an invoice | PUT /api/v2/client/invoices/1/ready | Not currently supported |
Marking an invoice as collected | PUT /api/v2/client/invoices/1/collected | Not currently supported |
Shipments
Use-case | REST | GraphQL |
---|---|---|
Listing shipments | GET /api/v2/client/invoices/:invoice_id/shipments | node (invoice) Example |
Showing shipments | GET /api/v2/client/invoices/:invoice_id/shipments/:shipment_id | node (invoice) Example |
Creating a shipment | POST /api/v2/client/invoices/:invoice_id/shipments | shipmentCreate Example |
Updating a shipment | PUT /api/v2/client/invoices/:invoice_id/shipments/:shipment_id | shipmentUpdate Example |
Shipping Profiles
Use-case | REST | GraphQL |
---|---|---|
Listing shipping profiles | GET /api/v2/shipping_profiles | shippingProfiles Example |
Getting a variants shipping profile | GET /api/v2/client/variants/1?include=shipping_profile | node (variant) Example |
Taxons
Use-case | REST | GraphQL |
---|---|---|
List Taxons | GET /api/v2/taxons | taxon Example |
Search for Taxons | GET /api/v2/taxons/search?name=Hybrid | taxonSearch Example |
Get Taxon Option Values | GET /api/v2/taxons/bikes | node (taxon) Example |
Multi-store memberships
Use-case | REST | GraphQL |
---|---|---|
List the members of a multi-store | GET /api/v2/client/multi_store_memberships | Not currently supported |
Variants
Use-case | REST | GraphQL |
---|---|---|
Listing variants without filters | GET /api/v2/client/variants | allAdverts Example |
Listing variants with filters | GET /api/v2/client/variants?external_id=VALUE | variantsWhere Example |
Listing an adverts variants | GET /api/v2/client/adverts/1/variants | node (advert) Example |
Get a single variant | GET /api/v2/client/variants/1 | node (variant) Example |
Get a single variant with additional resources | GET /api/v2/client/variants/1?include=shipping_parcel,shipping_profile | node (variant) Example |
Creating a variant | POST /api/v2/client/adverts/1/variants | advertUpsert Example |
Updating a variant | PUT /api/v2/client/adverts/1/variants/1 orPUT /api/v2/client/variants/1 | variantUpdate Example |
Updating count on hand for many variants | POST /api/v2/client/variants/stock_on_hand | Not currently supported |
Deleting a variant | DELETE /api/v2/client/adverts/1/variants/2 orDELETE /api/v2/client/variants/2 | variantDelete Example |
Examples
allAdverts - List Adverts without filters
query {
allAdverts {
nodes {
__typename
... on Advert {
legacyId
updatedAt
title
seller {
businessName
}
}
... on UnpublishedAdvert {
legacyId
updatedAt
details {
title
seller {
businessName
}
}
}
... on DeletedAdvert {
legacyId
id
updatedAt
}
}
}
}
advertsWhere - List Adverts with filters
query {
advertsWhere(variantSkus: ["VALUE"]) {
totalCount
nodes {
__typename
id
legacyId
title
published
online
displayable
vetted
requiresVetting
vettingRejected
variants {
nodes {
id
countOnHand
}
}
}
}
}
node (advert) - Get an individual advert
query {
node(id: "QWR2ZXJ0LTEwMDA3MDczNA==") {
... on Advert {
id
legacyId
title
lowestOriginalPrice
lowestPrice
variants {
nodes {
legacyId
sku
label
countOnHand
}
}
}
}
}
advertUpsert - Create an advert
mutation {
advertUpsert(
input: {
attributes: {
brandId: "QnJhbmQtNA=="
taxonId: "VGF4b24tMjc4"
title: "GlocalMe 4G Wireless Hot Spot"
description: "WiFi Hotspot powered by 4G"
price: "49.99"
attemptAutoPublish: true
images: [
{
sourceUrl: "https://example.com/router.jpg"
}
]
productFeatures:
["Fast charge", "Light weight", "4G compatible"]
advertOptionValues: [
{ optionValueId: "T3B0aW9uVmFsdWUtNzM2" }
]
variants: [
{
countOnHand: 1000
variantOptionValues: [
{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
]
}
]
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
advertsUpsert - Update an advert
mutation {
advertUpsert(
input: {
advertId: "QWR2ZXJ0LTEwMDA3MDczMA=="
attributes: {
price: "29.99"
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
advertVettingResubmit - Resubmit a rejected advert for vetting
mutation {
advertVettingResubmit(input:
{
advertIds: ["QWR2ZXJ0LTEwMDAwMjU3OA=="]
}) {
adverts {
nodes {
id
vetted
vettingRejected
vettingRejectedReason
requiresVetting
}
}
}
}
advertDelete - Delete an advert
mutation{
advertDelete(input: {
id: "QWR2ZXJ0LTEwMDAxMzAyNg=="
})
{
status
advert{
id
legacyId
}
errors{
field
messages
}
}
}
brands - List brands
query
{
brands{
nodes
{
id
name
slug
}
}
}
brandSearch - Search for a Brand
query{
brandSearch(keyword: "Giant")
{
nodes{
id
name
}
}
}
node (advert) - List an adverts images
query {
node(id: "QWR2ZXJ0LTEwMDA3MDczNA==") {
... on Advert {
id
legacyId
images{
nodes{
url
alt
id
}
}
}
}
}
node (variant) - List a variants images
query {
node(id: "VmFyaWFudC03ODAyOA==") {
... on Variant {
id
legacyId
images{
nodes{
url
alt
id
}
}
}
}
}
node (image) - Showing a single image
query {
node(id: "SW1hZ2UtMjg0OTQw") {
... on Image {
url
alt
}
}
}
advertUpsert - Adding an image to an advert
mutation {
advertUpsert(
input: {
attributes: {
brandId: "QnJhbmQtNA=="
taxonId: "VGF4b24tMjc4"
title: "GlocalMe 4G Wireless Hot Spot"
description: "WiFi Hotspot powered by 4G"
price: "49.99"
attemptAutoPublish: true
images: [
{
sourceUrl: "https://example.com/router.jpg"
}
]
productFeatures:
["Fast charge", "Light weight", "4G compatible"]
advertOptionValues: [
{ optionValueId: "T3B0aW9uVmFsdWUtNzM2" }
]
variants: [
{
countOnHand: 1000
variantOptionValues: [
{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
]
}
]
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
advertUpsert - Adding an image to a variant
mutation {
advertUpsert(
input: {
attributes: {
brandId: "QnJhbmQtNA=="
taxonId: "VGF4b24tMjc4"
title: "GlocalMe 4G Wireless Hot Spot"
description: "WiFi Hotspot powered by 4G"
price: "49.99"
attemptAutoPublish: true
images: [
{
sourceUrl: "https://example.com/router.jpg"
}
]
productFeatures:
["Fast charge", "Light weight", "4G compatible"]
advertOptionValues: [
{ optionValueId: "T3B0aW9uVmFsdWUtNzM2" }
]
variants: [
{
countOnHand: 1000
variantOptionValues: [
{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
]
images:[
{
sourceUrl: "https://example.com/router2.jpg"
}
]
}
]
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
advertUpsert - Updating an adverts image
mutation {
advertUpsert(
input: {
advertId: "QWR2ZXJ0LTEwMDA3MDczMA=="
attributes: {
images: [
{
imageId: "SW1hZ2UtMjg0OTQw"
sourceUrl: "https://example.com/router3.jpg"
}
]
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
variantUpdate - Updating a variants image
mutation{
variantUpdate(
input:
{
variantId: "VmFyaWFudC03ODAyOA=="
attributes: {
images: [
{
imageId: "SW1hZ2UtMjg0OTQw"
sourceUrl: "https://example.com/router4.jpg"
}
]
}
})
{
variant{
id
}
errors{
field
messages
}
}
}
advertUpsert - Delete an adverts image
mutation {
advertUpsert(
input: {
advertId: "QWR2ZXJ0LTEwMDA3NzY5MA=="
attributes: {
images: [
{
imageId: "SW1hZ2UtMzA1MTAy"
sourceUrl: null
}
]
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
variantUpdate - Delete a variants image
mutation{
variantUpdate(
input:
{
variantId: "VmFyaWFudC03ODAyOA=="
attributes: {
images: [
{
imageId: "SW1hZ2UtMjg0OTQw"
sourceUrl: null
}
]
}
})
{
variant{
id
}
errors{
field
messages
}
}
}
node (advert) - Listing an adverts documents
query {
node(id: "QWR2ZXJ0LTEwMDA3NzY5MA==") {
... on Advert {
id
legacyId
documents{
nodes{
filename
url
id
}
}
}
}
}
node (advertDocument) - Showing a single document
query {
node(id: "QWR2ZXJ0RG9jdW1lbnQtMzA1MTAz") {
... on AdvertDocument {
id
url
filename
}
}
}
advertUpsert - Adding a document to an advert
mutation {
advertUpsert(
input: {
attributes: {
brandId: "QnJhbmQtNA=="
taxonId: "VGF4b24tMjc4"
title: "GlocalMe 4G Wireless Hot Spot"
description: "WiFi Hotspot powered by 4G"
price: "49.99"
attemptAutoPublish: true
documents: [
{
sourceUrl: "https://example.com/router.pdf"
}
]
variants: [
{
countOnHand: 1000
variantOptionValues: [
{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
]
}
]
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
advertUpsert - Updating an adverts document
mutation {
advertUpsert(
input: {
advertId: "QWR2ZXJ0LTEwMDA3MDczMA=="
attributes: {
documents: [
{
documentId: "QWR2ZXJ0RG9jdW1lbnQtMzA1MTAz"
sourceUrl: "https://example.com/router3.pdf"
}
]
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
advertUpsert - Deleting an adverts document
mutation {
advertUpsert(
input: {
advertId: "QWR2ZXJ0LTEwMDA3NzY5MA=="
attributes: {
documents: [
{
documentId: "QWR2ZXJ0RG9jdW1lbnQtMzA1MTAz"
sourceUrl: "https://example.com/router3.pdf"
}
]
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
node (variant) - Listing a variants inventory
query {
node(id: "VmFyaWFudC0xNTIwMw==") {
... on Variant {
id
legacyId
countOnHand
inventories{
nodes{
price{amount}
salePrice{amount}
infiniteQuantity
countOnHand
seller{
id
legacyId
businessName
}
}
}
}
}
}
invoices - Listing invoices with no filters
query {
invoices{
nodes
{
id
legacyId
shippingCostCents
paidAt
statusFlags
discountCents
subtotalCents
totalCents
seller{
legacyId
}
metadata{
key
value
}
}
}
}
invoices - Listing invoices with filters
query {
invoices(filters: {updatedSince: "2023-05-16" }){
nodes
{
id
legacyId
shippingCostCents
paidAt
statusFlags
discountCents
subtotalCents
totalCents
seller{
legacyId
}
metadata{
key
value
}
}
}
}
invoices - Listing invoices with additional resources
query {
invoices(filters: {updatedSince: "2023-05-16" }){
nodes
{
id
legacyId
shippingCostCents
paidAt
statusFlags
discountCents
subtotalCents
totalCents
seller{
legacyId
}
metadata{
key
value
}
lineItems{
id
quantity
}
shipments{
id
dispatchedAt
carrier
}
}
}
}
node (invoice) - Show an individual invoice
query {
node(id: "SW52b2ljZS0xMzIxOA==") {
... on Invoice {
id
legacyId
shippingCostCents
paidAt
statusFlags
discountCents
subtotalCents
totalCents
seller{
legacyId
}
metadata{
key
value
}
lineItems{
id
quantity
}
shipments{
id
dispatchedAt
carrier
}
}
}
}
shipmentCreate - Send an invoice
mutation {
shipmentCreate(
input: {
invoiceId: "SW52b2ljZS0xMDQyMQ=="
dispatchedAt: "2023-06-07"
note: "Dispatched within SLA"
postageCarrierId: "U2hpcG1lbnRDYXJyaWVyLTY5"
trackingNumber: "12234"
shippedItems: [
{ lineItemId: "TGluZUl0ZW0tNDk5",
quantity: 1
}]
}
) {
errors {
field
messages
}
shipment {
id
createdAt
}
}
}
node (invoice) - Listing shipments on an invoice
query {
node(id: "SW52b2ljZS0xMzIxOA==") {
... on Invoice {
id
shipments{
id
dispatchedAt
carrier
trackingLink
trackingNumber
note
}
}
}
}
node (shipment) - Show an individual shipment
query {
node(id: "U2hpcG1lbnQtNzM1") {
... on Shipment {
id
id
dispatchedAt
carrier
trackingLink
trackingNumber
note
}
}
}
shipmentCreate - Create a shipment
mutation {
shipmentCreate(
input: {
invoiceId: "SW52b2ljZS0xMDQyMQ=="
dispatchedAt: "2023-06-07"
note: "Dispatched within SLA"
postageCarrierId: "U2hpcG1lbnRDYXJyaWVyLTY5"
trackingNumber: "12234"
shippedItems: [
{ lineItemId: "TGluZUl0ZW0tNDk5",
quantity: 1
}]
}
) {
errors {
field
messages
}
shipment {
id
createdAt
}
}
}
shipmentUpdate - Update a shipment
mutation {
shipmentUpdate(
input: {
shipmentId: "U2hpcG1lbnQtMzc4OTYz",
trackingNumber: "66666" }
) {
errors {
field
messages
}
shipment {
trackingNumber
}
}
}
shippingProfiles - Listing shipping profiles
query d{
shippingProfiles{
nodes{
id
name
legacyId
description
}
}
}
node (variant) - Getting a variants shipping profile
query {
node(id: "VmFyaWFudC03ODAyOA==") {
... on Variant {
id
shippingProfile{
id
legacyId
}
}
}
}
taxons - Listing taxons
query{
taxons{
nodes{
treeName
displayName
urlSlug
id
}
}
}
taxonSearch - Search Taxons
query{
taxonSearch(searchValue: "BBQ")
{
nodes
{
treeName
displayName
urlSlug
id
}
}
}
node (taxon) - Obtaining option types and values
query {
node(id: "VGF4b24tMTc4") {
... on Taxon {
id
treeName
taxonType
prototype{
optionTypes{
nodes{
name
id
appliedTo
fieldType
optional
presentation
optionValues{
nodes{
id
name
displayName
}
}
}
}
}
}
}
}
allAdverts - List variants no filters
query {
allAdverts {
nodes {
__typename
... on Advert {
variants {
nodes {
countOnHand
sku
barcode
lowestOriginalPrice
lowestPrice
maxPurchaseQuantity
minPurchaseQuantity
}
}
}
... on UnpublishedAdvert {
details {
variants {
nodes {
countOnHand
sku
barcode
lowestOriginalPrice
lowestPrice
maxPurchaseQuantity
minPurchaseQuantity
}
}
}
}
... on DeletedAdvert {
legacyId
id
updatedAt
}
}
}
}
variantsWhere - List variants with filters
query {
variantsWhere(
variantFilters:
{skus: ["sku-1", "sku-2"]}) {
nodes {
countOnHand
sku
barcode
lowestOriginalPrice
lowestPrice
maxPurchaseQuantity
minPurchaseQuantity
}
}
}
node (advert) - Listing an adverts variants
query {
node(id: "QWR2ZXJ0LTEwMDA3MDcyOQ==") {
... on Advert {
variants {
nodes {
countOnHand
sku
barcode
lowestOriginalPrice
lowestPrice
maxPurchaseQuantity
minPurchaseQuantity
}
}
}
}
}
node (variant) - Get a single variant
query {
node(id: "VmFyaWFudC03ODAyMw==") {
... on Variant {
id
countOnHand
sku
barcode
lowestOriginalPrice
lowestPrice
maxPurchaseQuantity
minPurchaseQuantity
}
}
}
node (variant) - Get a single variant with additional resources
query {
node(id: "VmFyaWFudC03ODAyMw==") {
... on Variant {
id
countOnHand
sku
barcode
lowestOriginalPrice
lowestPrice
maxPurchaseQuantity
minPurchaseQuantity
shippingParcel{
length
}
}
}
}
advertUpsert - Creating a variant
mutation {
advertUpsert(
input: {
attributes: {
brandId: "QnJhbmQtNA=="
taxonId: "VGF4b24tMjc4"
title: "GlocalMe 4G Wireless Hot Spot"
description: "WiFi Hotspot powered by 4G"
price: "49.99"
attemptAutoPublish: true
images: [
{
sourceUrl: "https://example.com/router.jpg"
}
]
productFeatures:
["Fast charge", "Light weight", "4G compatible"]
advertOptionValues: [
{ optionValueId: "T3B0aW9uVmFsdWUtNzM2" }
]
variants: [
{
countOnHand: 1000
variantOptionValues: [
{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
]
}
]
}
}
) {
status
advert {
id
legacyId
}
errors {
field
messages
}
}
}
variantUpdate - Updating a variant
mutation {
variantUpdate(
input: {
variantId: "VmFyaWFudC03ODAyMw=="
attributes:
{
countOnHand: 78,
sku: "SKU-1234",
salePrice: 201 }
}
) {
variant {
id
}
errors {
field
messages
}
}
}
variantDelete - Deleting a variant
mutation {
variantDelete(input:
{ id: "VmFyaWFudC03ODAyMw==" }) {
variant {
countOnHand
}
errors {
field
messages
}
}
}
Next Up: Object & Field Mapping