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.

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.common-ground.io/graphql/graphql',
  cache: new InMemoryCache(),
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'CommonGround-Origin': 'www.my-store.com'
  },
});

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 YOUR_TOKEN" \
  -H "CommonGround-Origin: www.my-store.com" \
  -d '{"query": "query { items { items { _id title } } }"}' \
  https://api.common-ground.io/graphql/graphql

JavaScript (fetch)​

const response = await fetch('https://api.common-ground.io/graphql/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN',
    'CommonGround-Origin': 'www.my-store.com'
  },
  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.common-ground.io/graphql/graphql',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_TOKEN',
        'CommonGround-Origin': 'www.my-store.com'
    },
    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 (Authorization, CommonGround-Origin)
  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​