The GraphQL API allows queries to be made to Kibo's Storefront APIs in query syntax, allowing for mutations and modification of REST data. It is accessible directly by API call or through a Playground interface, along with a JavaScript client for handling authentication.
This guide describes how to install, configure, and authenticate a GraphQL client with code samples for example queries.
Access GraphQL
The GraphQL API can reached by appending /graphql to your Kibo Storefront home URL.
curl -X POST 'https://t00000.sandbox.mozu.com/graphql' \ -H 'content-type: application/json' \ -H 'Authorization: Bearer ' \
Include the following request headers:
Authorization(required): Kibo API application auth token
The request body should include a JSON encoded body in the following form:
{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}query(required): GraphQL query as a stringoperationName(optional): Only required if multiple operations are present in queryvariables(optional): Data to be passed to query
GraphQL Playground
The interactive GraphQL console, called the Playground, can be accessed from your site's front-end by appending /graphql to your storefront's homepage URL to access this tool in the browser.
You must first include your credentials (generated by the cookie from the front end site) by opening the gear icon in the top right corner and setting "request.credentials": "include" as shown below:
Then you will be able to build queries. GraphQL's syntax is displayed in the left pane of the Playground, while the JSON results will be displayed in the right pane once the call is made.
Code Samples
Get Product
query GetProduct {
product(productCode: "1000165") {
productCode
content {
productFullDescription
productName
productImages {
imageUrl
}
}
categories {
content {
name
}
}
price {
price
salePrice
}
}
}
Get Categories
query GetCategories {
categories(filter: "categoryCode eq shoes") {
items {
categoryCode
content {
name
slug
description
}
}
}
}Product Search
query Search {
productSearch(query: "hammer") {
totalCount
items {
productCode
content {
productName
}
}
facets {
label
field
values {
label
value
isApplied
}
}
}
}
Get Current Cart
* Requires a shopper access token to be sent as Bearer auth.
query GetCurrentCart {
currentCart {
total
subtotal
items {
product {
productCode
name
}
}
}
}Get Cart By ID
query GetCart {
cart(cartId: "12934ccc00db5100015d062b00007656") {
total
subtotal
items {
product {
productCode
name
}
}
}
}Add To Current Cart
* Requires a shopper access token to be sent in the header as Bearer auth.
mutation addToCart($addToCartInput:CartItemInput!) {
addItemToCurrentCart(cartItemInput: $addToCartInput) {
total
id
product {
productCode
}
}
}Variables:
{
"addToCartInput": {
"product": {
"productCode": "SHOE-12"
},
"quantity": 1,
"fulfillmentMethod": "Ship"
}
}Error Responses
GraphQL error messages include the following data.
message: A detailed description of the error and root cause. This is always provided in the error response.path: A list of the query fields leading up to the error. This is only included when the error can be traced back to a particular field.extensions: Any additional information that may be included if applicable.code: An HTTP error code used by the Kibo APIs as documented here.
This information is provided in the below format:
{
"errors": [
{
"message": "Description of the error.",
"path": ["path"],
"extensions": {
"code": "Example"
}
}
]
}GraphQL Client
There is a JavaScript Kibo GraphQL client available to handle API authentication and assist with registered and anonymous shopper authentication.
Prerequisites
If this client library is used in a browser environment, ensure your application is configured with storefront-only permissions as the API Key and secret will be visible.
Installation
To install the GraphQL client, run the following command:
npm install @kibocommerce/graphql-client
Configuration
To create an instance of the GraphQL client, the following configuration is required:
{
"accessTokenUrl": "https://t00000.sandbox.mozu.com/api/platform/applications/authtickets/oauth",
"clientId": "KIBO_APP.1.0.0.Release",
"sharedSecret": "12345_Secret",
"apiHost": "https://kibo-site.com"
}apiHost- Link to your GraphQL API instance.accessTokenUrl- Link to the Authentication Server, used to request an access token from Kibo's OAuth 2.0 service.clientId- Unique Application (Client) ID of your application.sharedSecret- Secret API key used to authenticate your application.
Based on the config, this integration will handle authenticating your application against the API using your Client ID and Shared Secret. These can be found from your Dev Center. For more information about the Dev Center and authentication, see Getting Started.
Authentication Hooks
Hooks can be provided to the CreateApolloClient method when creating a client that will execute on AuthTicket change, read, and remove events.
export interface KiboApolloClientConfig {
api: KiboApolloApiConfig;
clientAuthHooks: {
onTicketChange: (authTicket: UserAuthTicket) => void;
onTicketRead: () => UserAuthTicket;
onTicketRemove: () => void;
};
}The auth ticket is passed as requests to the GraphQL server as a Bearer auth header, used to identify and authorize the user. This auth ticket works for both authenticated and anonymous shoppers, allowing for guest checkout scenarios.
These built-in hooks allow customization on storage methods for the user's auth ticket.
import { CreateApolloClient } from '@kibocommerce/graphql-client';
let currentTicket = getUserAuthorizationFromCooke();
const clientAuthHooks = {
onTicketChange: (authTicket) => {
currentTicket = authTicket;
setUserAuthorizationCookie(authTicket);
},
onTicketRead: () => {
return currentTicket;
},
onTicketRemove: () => {
removeUserAuthorizationCookie();
}
}
const client = CreateApolloClient({
api: config,
clientAuthHooks
});
const query = `query getCurrentCart {
currentCart {
total
}
}`
const { data } = await client.query({ query });Proxy Requests in Development
If you would like to see the requests to the GraphQL server, you need to set the HTTPS_PROXY environment variable to the proxy application you are using.
HTTPS_PROXY="http://127.0.0.1:8866"