GraphQL introduction

GraphQL is a query language for APIs. Facebook developed it in 2012 and open-sourced it in 2015; it is now maintained by the GraphQL Foundation. The CoCoCo API is a GraphQL API, so this page covers the concepts you need to read the rest of the API documentation.

What makes GraphQL different

• One endpoint. Every request goes to POST /graphql on your tenant host. The operation in the request body decides what happens.
• You choose the fields. The response has exactly the shape of your query: no missing fields, no extra ones.
• Related data in one request. A job, its components and its customer come back in a single call.
• A typed schema. Every field and argument has a type, so tools can autocomplete and validate queries before you send them.

The schema

The schema describes everything the API offers. It has three entry points:

• Query for reading,
• Mutation for writing,
• Subscription for event streams.

Types are written in the GraphQL schema language (SDL). This is part of the real JobState type:

type JobState {
  id: JobID!
  name: String!
  quantity: Int!
  status: JobStatus!
  dueAt: ISO8601
  components: [ComponentState!]!
}

• ! means the value is never null.
• [ComponentState!]! is a list that is never null and never contains nulls.
• JobID and ISO8601 are custom scalars: a typed ID, and a timestamp string.
• JobStatus is an enum, a fixed set of allowed values.

You can download the full schema from GET /graphql/schema, and browse it on this site in the API reference.

Queries

A query names the fields it wants:

query JobWithComponents {
  getJob(id: "job_01M0R249JMETNBM1Z7466MXGZD") {
    name
    status
    components {
      name
      kind
      quantity
    }
  }
}

The response mirrors the query:

{
  "data": {
    "getJob": {
      "name": "Spring catalogue 2027",
      "status": "PREPRESS",
      "components": [
        { "name": "Cover", "kind": "COVER", "quantity": 5000 },
        { "name": "Text block", "kind": "TEXT", "quantity": 5000 }
      ]
    }
  }
}

Arguments

Fields can take arguments. List queries use them for paging, filtering and sorting:

query PressQueue {
  listJobs(
    first: 10
    filter: { status: { eq: "PRESS" } }
    sort: [{ field: DUE_AT, direction: ASC }]
  ) {
    edges {
      node {
        id
        name
        dueAt
      }
    }
  }
}

Aliases

An alias renames a field in the response, which lets you ask for the same field twice with different arguments:

query StageCounts {
  prepress: aggregateJobs(filter: { status: { eq: "PREPRESS" } }) {
    count
  }
  press: aggregateJobs(filter: { status: { eq: "PRESS" } }) {
    count
  }
}

Variables

Pass values separately from the query text instead of building strings. Declare each variable with its type:

query GetJob($id: JobID!) {
  getJob(id: $id) {
    id
    name
    status
  }
}

{ "id": "job_01M0R249JMETNBM1Z7466MXGZD" }

Mutations

Mutations change data and then return fields, just like a query. In CoCoCo they return the changed record and a list of validation errors:

mutation CreateJob($input: CreateJobInput!) {
  createJob(input: $input) {
    job {
      id
      status
    }
    errors {
      path
      message
    }
  }
}

{ "input": { "name": "Menu cards", "quantity": 500 } }

Fragments

A fragment is a named, reusable selection:

fragment CustomerCard on CustomerState {
  id
  name
  email
}

query Customers {
  listCustomers(first: 10) {
    edges {
      node {
        ...CustomerCard
      }
    }
  }
}

Subscriptions

A subscription keeps a connection open and receives an event each time something happens. The CoCoCo API has subscriptions such as dataChangeEvents and statusEvents. Read GraphQL tooling before you build an integration on them.

Introspection

A GraphQL API can describe itself. Tools use this to power autocompletion and documentation:

query SchemaRoots {
  __schema {
    queryType {
      name
    }
    mutationType {
      name
    }
    subscriptionType {
      name
    }
  }
}

Errors

A GraphQL response always has the same outer shape: data with the result, and errors when something went wrong at the operation level (an invalid query, a missing permission). CoCoCo mutations additionally report validation problems inside their payload. Core patterns describes both.

Next steps

• API overview: endpoint, authentication and the main domains.
• Core patterns: pagination, filtering, sorting and errors.
• GraphQL for REST users and GraphQL for XML users, if you are coming from those styles of API.
• The GraphQL playground in the console (/#/graphql-playground), to try queries against your own tenant.