GraphQL tooling

Any tool that can send an HTTP POST with a JSON body works with the CoCoCo API. This page lists what you need to set up in the common ones. The settings are always the same:

Setting	Value
URL	https://<your-tenant-host>/graphql
Method	POST
Headers	Authorization: Bearer <API token>, Content-Type: application/json
Schema (SDL)	https://<your-tenant-host>/graphql/schema

API overview explains how to get a token.

Console playground

The quickest way to try a query is the GraphQL playground in the CoCoCo console, at /#/graphql-playground. It runs requests as your signed-in user, has a schema explorer and a variables panel, and needs no token. The console's API docs (/#/docs) document the operations and types.

Getting the schema

Most tools need the schema. Download it once and keep it next to your code:

curl -s https://<your-tenant-host>/graphql/schema -o schema.graphql

The schema endpoint needs no token, so don't send one.

Download it again when you upgrade, and re-run your validation or code generation to catch changed fields.

HTTP clients

The code examples read two environment variables: COCOCO_URL (for example https://<your-tenant-host>) and COCOCO_TOKEN, as in Calling the CoCoCo API.

curl

curl -s https://<your-tenant-host>/graphql \
  -H "Authorization: Bearer $COCOCO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query Jobs($first: Int) { listJobs(first: $first) { totalCount edges { node { id name status } } } }","variables":{"first":5}}'

Postman and Insomnia

Both have a GraphQL body type. Create a POST request to the URL above, set the authorization to Bearer token with your API token, and choose GraphQL as the body. Both can fetch the schema by introspection for autocompletion; if that is not available, import the downloaded schema.graphql.

Client libraries

The API is standard GraphQL over HTTP, so general-purpose clients work. Set the URL and the Authorization header; nothing else is CoCoCo-specific.

graphql-request (JavaScript)

A small client, good for scripts and server-side integrations:

import { GraphQLClient, gql } from 'graphql-request'

const client = new GraphQLClient(`${process.env.COCOCO_URL}/graphql`, {
  headers: { Authorization: `Bearer ${process.env.COCOCO_TOKEN}` },
})

const query = gql`
  query OpenJobs($first: Int) {
    listJobs(first: $first, filter: { status: { notIn: ["COMPLETED", "CANCELLED"] } }) {
      edges {
        node {
          id
          name
          status
        }
      }
    }
  }
`

const data = await client.request(query, { first: 25 })

Plain fetch

async function cococo(query, variables = {}) {
  const res = await fetch(`${process.env.COCOCO_URL}/graphql`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.COCOCO_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables }),
  })
  const body = await res.json()
  if (body.errors?.length) throw new Error(body.errors.map(e => e.message).join('; '))
  return body.data
}

const { ping } = await cococo('query { ping }')

Python

import os
import requests

def cococo(query, variables=None):
    res = requests.post(
        f"{os.environ['COCOCO_URL']}/graphql",
        headers={"Authorization": f"Bearer {os.environ['COCOCO_TOKEN']}"},
        json={"query": query, "variables": variables or {}},
        timeout=30,
    )
    res.raise_for_status()
    body = res.json()
    if body.get("errors"):
        raise RuntimeError("; ".join(e["message"] for e in body["errors"]))
    return body["data"]

data = cococo("query Customers { listCustomers(first: 10) { edges { node { id name } } } }")

Apollo Client, urql and others

Apollo Client, and urql with its Graphcache exchange, keep a normalised cache. Configure them with the URL and an Authorization header in the same way. They identify records by __typename and id by default, which suits the CoCoCo API because every record has a stable id.

Code generation

GraphQL Code Generator turns the schema and your queries into typed code. Point it at the downloaded schema file:

// codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli'

const config: CodegenConfig = {
  schema: 'schema.graphql',
  documents: ['src/**/*.graphql'],
  generates: {
    'src/generated/': { preset: 'client' },
  },
}

export default config

Custom scalars such as JobID, ISO8601 and CurrencyISO are strings on the wire; map them to string in your generator's scalar settings. JSON and JSONMap carry arbitrary JSON values.

Editor support

Editor plugins validate and autocomplete queries in your code when they know the schema. Most of them, including the GraphQL extension for VS Code and the JetBrains GraphQL plugin, read a graphql.config.yml in your project:

schema: schema.graphql
documents: 'src/**/*.{graphql,js,ts}'

Subscriptions

The API has GraphQL subscriptions (dataChangeEvents, statusEvents and a few more) over a WebSocket at wss://<your-tenant-host>/graphql-ws using the graphql-transport-ws protocol.

At present subscriptions authenticate with a signed-in console session only. An API token passed in the WebSocket connection parameters is not used, so do not build an integration on subscriptions with an API token. To follow changes from an integration, poll the records you track.