Frontend API: Setup

The library can be used in any bundled JavaScript application, in server or client contexts.

Installation

Add swell-js dependency to your project:

Initialization

The client uses your store ID and public key for authorization. You can find these in your dashboard under Developer > API keys.

import swell from 'swell-js'
// Initialize client with your store ID and a public key
swell.init('<store-id>', '<public_key>')

Options

useCamelCase

If your application uses camelCase, you can set a flag to transform the API's snake_case responses. This works on objects you pass to it as well.

Example

const options = {
  useCamelCase: true, // default is false
};

swell.init('<store-id>', '<public_key>', options)

The GraphQL library can be used in any bundled GraphQL application, in server or client contexts.

Accessing the GraphQL endpoint

The endpoint will reference your Swell store domain, which can be found at the top of the API Keys section of the Developer menu in the dashboard.

Access URL

https://{store ID}.swell.store/graphql

For example, if Urbul gro-Orkulg wanted to use his Swell store ID (slash-n-smash), the endpoint would be https://slash-n-smash.swell.store/graphql.

Authorization

Before you are able to query your endpoint, you will need to add an authorization header to your GraphQL client of choice, or to the HTTP Headers section if using the Playground. To do so, you will need a public key from your store, which can be acquired through your Swell store dashboard under Developer > API.

Depending on your preference, you can use an existing key or create and use a new public key by clicking the Add public key button and providing a description. Your new key will be displayed at the top of the Public keys table.

Example authorization key

{
  "Authorization": "pk_1234abcd5678efgh9101112ijklmnop"
}

Playground

Explore queries, current schema, and data structures with our GraphQL playground. To access the playground, enter the URL below in your browser:

Playground access URL

https://{store ID}.swell.store/playground

Within the Playground, you have access to:

An interactive way to explore fields and queries.
Instant feedback through a panel that shows you the responses to your queries.
A Docs tab to reference available types, queries, and mutations.
A Schema tab for an overview of your store schema and the option to download it.

💡

For our GraphQL playground, we are making use of the graphql-playground project. Check out these resources for more info →

Working with sessions

Some queries and mutations need an active session to be established (for example, cart operations). For that, you’ll need to manage a session token and include it within your requests’ headers. This will allow you to continue interacting with the same session throughout your requests.

Example API Response

# Example API Response

Response Headers
...
"X-Session": "f07c9fadde8fca959fe3152e1d949dc..."
...


Response Data
{
  "data": {
    "addCartItem": {
      "items": {
        "product": {
          "id": "62b1e30767145000197b2bbf",
          "name": "Fine Iron Warhammer"
         },
         "quantity": 2,
         "price": 70
        }
      }
    }
  }
}

You can use this x-session token by adding it to the list of headers of your GraphQL client or Playground session. For example, using the graphql-request client:

GraphQL-request example

# graphql-request example

const client = new GraphQLClient("my-store.swell.store/graphql", {
  headers: {
    "x-session": "f07c9fadde8fca959fe3152e1d949dc..."
  }
});

Most GraphQL clients should support access to the headers and the ability to set the session header for subsequent requests.