GraphQL API cheat sheet

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 field types in Hygraph

Embrace a low-code API management layer approach to unify your microservices and operations, and focus on growing your business model rather than maintaining it.

Learn about all the 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

he 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.

Working with Hygraph’s GraphQL 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 Hygraph’s GraphQL 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
  }
}

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

Contact sales Get started