Introduction to GraphQL

What is an API?

An API (Application Programming Interface) is a way for software systems to talk to each other. When you use the Worksome web app, your browser communicates with Worksome’s servers behind the scenes. The API is the same interface, but designed for your own software to use directly.

With the Worksome API, your applications can do things like:

• Read data — list active hires, check invoice statuses, view compliance requirements
• Create records — draft new hires, create job postings
• React to changes — receive notifications when a contract is accepted or a hire is updated (via Webhooks)

You send a request (what you want), and the API returns a response (the data or confirmation). All communication happens over HTTPS, so it works from any programming language or tool that can make web requests.

If you’re not a developer, you don’t need to use the API directly. Zapier lets you connect Worksome to other tools without writing code.

Coming from REST?

If you’ve worked with REST APIs before, here are the key differences with GraphQL:

A practical example

A REST API might split fetching a hire with its contract and worker into three requests:

GET /hires/123
GET /contracts/456
GET /workers/789

In GraphQL, you do it in one:

{
  hire(id: "SGlyZToxMjM0") {
    id
    activeStatus
    latestContract {
      rate
      currency
      startDate
    }
    worker {
      name
      email
    }
  }
}

You get exactly the fields you asked for — no more, no less. This makes responses smaller and faster, especially when you only need a few fields from each entity.

Reading vs writing

• Queries are the GraphQL equivalent of GET — they read data.
• Mutations are the equivalent of POST/PUT/DELETE — they create or change data.

Both use the same endpoint and the same POST method. The operation type (query or mutation) tells the API what you intend to do.

GraphQL terminology

You will probably encounter some new terminology in the Worksome GraphQL API reference docs.

Schema

A schema defines a GraphQL APIs type system. It describes the complete set of possible data (objects, fields, relationships, everything) that a client can access. Calls from the client are validated and executed against the schema. A client can find information about the schema via introspection. A schema resides on the GraphQL API server. For more information, see “Discovering the GraphQL API.”

Field

A field is a unit of data you can retrieve from an object. As the official GraphQL docs say:
“The GraphQL query language is basically about selecting fields on objects.”

The official spec also says about fields:

All GraphQL operations must specify their selections down to fields which return scalar values to ensure an unambiguously shaped response.

This means that if you try to return a field that is not a scalar, schema validation will throw an error. You must add nested subfields until all fields return scalars.

Argument

An argument is a set of key-value pairs attached to a specific field. Some fields require an argument. Mutations require an input object as an argument.

Implementation

A GraphQL schema may use the term implements to define how an object inherits from an interface.

Here’s a contrived example of a schema that defines interface X and object Y:

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

This means object Y requires the same fields/arguments/return types that interface X does, while adding new fields specific to object Y. (The ! means the field is required.)

In the reference docs, you’ll find that:

• Each object lists the interface(s) from which it inherits under Implements.

• Each interface lists the objects that inherit from it under Implementations.

Connection

Connections let you query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API.

It’s helpful to picture a graph: dots connected by lines. The dots are nodes, the lines are edges. A connection defines a relationship between nodes.

Node

Node is a generic term for an object. You can look up a node directly, or you can access related nodes via a connection. If you specify a node that does not return a scalar, you must include subfields until all fields return scalars.

Discovering the GraphQL API

GraphQL is introspective. This means you can query a GraphQL schema for details about itself.

• Query __schema to list all types defined in the schema and get details about each:

  query {
    __schema {
      types {
        name
        kind
        description
        fields {
          name
        }
      }
    }
  }
  

• Query __type to get details about any type:

  query {
    __type(name: "Company") {
      name
      kind
      description
      fields {
        name
      }
    }
  }
  

You can also run an introspection query of the schema as a regular POST request:

curl -H "Authorization: Bearer ${WORKSOME_API_TOKEN}" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"query": "{ __schema { types { name kind } } }"}' \
     https://api.worksome.com/graphql

The results are in JSON, so we recommend pretty-printing them for easier reading and searching. You can use a command-line tool like jq or parse the results using a language-specific pretty-printer for this purpose.