Take part in the GraphQL Challenges Survey 2023

GraphQL API cheatsheet

Get started with building your own production ready GraphQL API within minutes using Hygraph. Here’s a cheatsheet to bring you up to speed!

What is GraphQL?

GraphQL is an open-source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data. Maintained and developed primarily via the GraphQL Foundation, GraphQL has had incredible adoption across a variety of verticals and use cases with organizations like Twitter, Facebook, Expedia, Shopify, and Hygraph to name a few.

3 Reasons we love GraphQL

Data Fetching: GraphQL gives you exactly what you ask for. No over or under fetching.
Schema & Type Safety: GraphQL uses a strongly typed system to define the capabilities of an API.
Content Federation: GraphQL can combine multiple APIs into a single schema to make it accessible to the client.

No-code GraphQL API Schema Builder in Hygraph

Field Types

Learn more about Hygraph's GraphQL Field Types

String

A string is just a simple string field. Hygraph supports single-line text, multi-line text, markdown, and slug, as string variants.

Rich Text

The Rich Text field is an advanced string field that returns your content in `raw`, `html`, `markdown`, and `text`.

Integer

Integers are whole numbers, and are often used to reference price in cents, stock quantities etc.

Float

Floating point numbers represent fractional values with precision, such as distance, weight, volume, etc.

Boolean

Booleans are used for entries that should have a `true` or `false` value.

Date

The Date field type adheres to ISO 8601 standard. This means, October 7, 1989 is represented as 1989-10-07.

Date and Time

The DateTime field type also adheres to ISO 8601 standard, allowing you to set specific times on dates.

JSON

Often used for storing large amounts of data, this field could be seen as an “escape hatch” that could lose you some GraphQL benefits.

Asset

Assets are connected to models through a reference field. Assets can be any file type, not just images.

Color

The Color field stores values that can be retrieved in several formats like HEX, RGBA, and CSS color values.

Location

The Location field type returns `latitude`, `longitude`, and `distance` Float values.

Enumeration

Enums are a predefined list of values inside your GraphQL schema, and can be referenced by any content models.

Reference (Simple)

Relations allow you to connect multiple models. In Hygraph they come as one-way or two-way references.

Reference (Union)

GraphQL Union Types (or Polymorphic Relations) allow you to define a list of possible relations, and decide which one to use.

Remote

Remote fields allow you to programmatically bring external data into your graph, without copying them into the CMS.

Get Started

Test these fields out using Hygraph’s no-code schema builder.

Working with Hygraph’s GraphQL Content API

Working with the Query API

Hygraph automatically generates queries for fetching single, and multiple entries for each defined content type belonging to your project.

Learn more about working with our Queries API

Fetching Single Entries

The `post` query is what you would use to fetch a single entry from the CMS.

{
  post(where: { id: "..." }) {
    id
    title
  }
}

Fetching Multiple Entries

The `posts` query is what you would use to fetch multiple entries from the CMS.

{
  posts {
    id
  }
}

Fetching Relations

Imagine `posts` have a one to many relation with comments. With GraphQL you can query the related `comments` in the same request.

{
  posts {
    id
    comments {
      id
      author
    }
  }
}

Fetching Localizations

When fetching one or more entries, you can also fetch the localized entries. The default locale is set to `en`.

{
  post(where: { id: "..." }, locales: [en, fr, de]) {
    title
  }

  posts(locales: [en, fr, de]) {
    title
  }
}

Filtering on Stages

When fetching entries, you can also specify the content `stage`. The default content stage is set to `DRAFT`.

{
  post(where: { id: "..." }, stage: PUBLISHED) {
    title
  }

  posts(stage: PUBLISHED) {
    title
  }
}

Fetching Versions

You can fetch all data of a specific entry at a point in time using the automatically generated version query.

{
  postVersion(where: { id: "abc123", revision: 1, stage: PUBLISHED }) {
    id
    revision
    data
  }
}

Combining Arguments

It is also possible to pass multiple arguments at a time. Let’s get the first 3 published posts by time, where the title contains "Hygraph".

{
  posts(
    where: { title_contains: "Hygraph" }
    orderBy: createdAt_DESC
    first: 3
    stage: PUBLISHED
  ) {
    id
  }
}

Combining Queries

Multiple queries can be executed in parallel via a single request to your endpoint. Let's fetch our a single, and multiple posts in one request.

{
  post(where: { id: "..." }) {
    id
    title
  }

  posts {
    id
    title
  }
}

Directives

We support both the @skip and @include directives for use in your schema.

query ($includeAuthor: Boolean!) {
  posts {
    id
    title
    author @include(if: $includeAuthor) {
      name
    }
  }
}

Variables

It's recommended you use GraphQL variables when working with queries that use any variable data values.

query GetPostBySlug($slug: String!) {
  post(where: { id: $id }) {
    id
    title
  }
}

Working with the Mutations API

Your project endpoint exposes GraphQL mutations. The mutations API allows you to interact with content ouside of Hygraph using GraphQL.

Learn more about working with our Mutations API

Create Entries

When creating new content entries, the `data` argument will have an associated input type that is specific to your content model.

mutation {
  createProduct(
    data: {
      name: "Face Mask", 
      slug: "face-mask", 
      price: 1000 }
    ) {
    id
    name
    slug
    price
  }
}

Update Entries

When updating single content entry, you must specify the unique `where` criteria of which you want to update, as well as the new `data`.

mutation {
  updateProduct(
    where: { id: "ckgcd5hzc01wd0a446vd3kqrs" }
    data: { price: 100 }
  ) {
    id
    name
    price
  }
}

Batch Mutations

Hygraph supports batch mutations that can be applied to "many" entries at once. They comply with Relay connection type specification.

mutation {
  updateManyProductsConnection(
    where: { featured: true }
    data: { featured: false }
  ) {
    edges {
      node {
        featured
      }
    }
  }
}

Insert Mutations

When inserting related entries, you can `connect` entries at a given position. The position of entries reflects that fetching relations.

mutation {
  updateAuthor(
    where: { id: "..." }
    data: { posts: { connect: { position: { before: "..." } } } }
  ) {
    id
  }
}

Delete Entries

Similar to updating, and upserting entries, you can specify using `where` the entries you want to delete.

mutation {
  deleteProduct(where: { id: "..." }) {
    id
    name
    slug
    price
  }
}

Upsert Entries

The upsert mutation allows you to create, or update a content entry based on whether the unique `where` values exist.

mutation {
  upsertProduct(
    where: { slug: "face-mask" }
    upsert: {
      create: { name: "Face Mask", slug: "face-mask", price: 1000 }
      update: { name: "Face Mask", slug: "face-mask", price: 1000 }
    }
  ) {
    id
    name
    slug
    price
  }
}

GraphQL API cheatsheet

What is GraphQL?

3 Reasons we love GraphQL

No-code GraphQL API Schema Builder in Hygraph

Field Types

String

Rich Text

Integer

Float

Boolean

Date

Date and Time

JSON

Asset

Color

Location

Enumeration

Reference (Simple)

Reference (Union)

Remote

Get Started

Working with Hygraph’s GraphQL Content API

Working with the Query API

Fetching Single Entries

Fetching Multiple Entries

Fetching Relations

Fetching Localizations

Filtering on Stages

Fetching Versions

Combining Arguments

Combining Queries

Directives

Variables

Working with the Mutations API

Create Entries

Update Entries

Batch Mutations

Insert Mutations

Delete Entries

Upsert Entries

Other Hygraph Content API Capabilities

Filtering

Ordering

Pagination

Content Stages

Localization

Assets

Get Started

Get started for free, or request a demo to discuss larger projects