Skip to main content

Developer Tools

Tools and methods for working with Common Ground's GraphQL APIs. Choose the approach that fits your development environment.

Endpoints and authentication​

APIEndpointAuth
Admin APIhttps://api-admin.common-ground.io/graphqlAuthorization: Bearer sk-… only
Client APIhttps://your-shop-name.common-ground.io/graphqlStore from the subdomain URL; Authorization: Bearer <jwt> for authenticated operations

See Admin API Overview and Client API Overview for full details. Examples below use the Admin API.

GraphQL Clients​

GraphQL clients handle caching, error management, and type safety:

  • Apollo Client - Popular client for JavaScript/React applications
  • Relay - Facebook's GraphQL client framework, optimized for performance
  • urql - Lightweight and highly customizable GraphQL client
  • graphql-request - Minimal GraphQL client for Node.js and browsers

Apollo Client Example​

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://api-admin.common-ground.io/graphql',
  cache: new InMemoryCache(),
  headers: {
    'Authorization': 'Bearer sk-...'
  },
});

const GET_ITEMS = gql`
  query GetItems {
    items(pagination: { page: 1, limit: 10 }) {
      items {
        _id
        title
        price
      }
    }
  }
`;

const { data } = await client.query({ query: GET_ITEMS });

HTTP Libraries​

Use standard HTTP libraries to make GraphQL requests. GraphQL operations use POST requests with a JSON-encoded body.

curl​

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-..." \
  -d '{"query": "query { items { items { _id title } } }"}' \
  https://api-admin.common-ground.io/graphql

JavaScript (fetch)​

const response = await fetch('https://api-admin.common-ground.io/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk-...'
  },
  body: JSON.stringify({
    query: `
      query GetItems {
        items(pagination: { page: 1, limit: 10 }) {
          items {
            _id
            title
          }
        }
      }
    `
  })
});

const data = await response.json();

Python (requests)​

import requests

response = requests.post(
    'https://api-admin.common-ground.io/graphql',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sk-...'
    },
    json={
        'query': '''
          query GetItems {
            items(pagination: { page: 1, limit: 10 }) {
              items {
                _id
                title
              }
            }
          }
        '''
    }
)

data = response.json()

GraphQL IDEs​

Interactive environments for exploring schemas, writing queries, and testing operations:

  • GraphiQL - In-browser IDE for exploring GraphQL
  • GraphQL Playground - Feature-rich IDE with query history
  • Insomnia - REST and GraphQL client with autocomplete
  • Postman - API client with GraphQL support
  • Altair - Desktop app, browser extension, or web app

Load the downloadable schema files into these IDEs for autocomplete and validation.

Schema Tools​

Downloadable schema files can be used with:

Download schema files from:

Getting Started​

Choose your path:

I want to use Apollo Client

  1. Install: npm install @apollo/client
  2. Configure client with your API endpoint and authentication headers
  3. Write queries using gql template literals
  4. Execute queries with client.query() or client.mutate()

I want to use fetch/HTTP libraries

  1. Set up POST requests to the GraphQL endpoint
  2. Include Content-Type: application/json header
  3. Include authentication headers for your API (Authorization for Admin secret keys or Client JWTs as needed)
  4. Send JSON body with query and optional variables fields
  5. Parse JSON response and check for errors array

I want to use a GraphQL IDE

  1. Download the schema file for your API
  2. Load schema into your IDE
  3. Configure authentication headers
  4. Write and test queries interactively

Further Reading​