Introducing our new GraphQL API

You know us, we’re careful about our APIs – our GraphQL APIs have seen production use for over a year, but it's not till now we're declaring them officially out of beta. You can try it out by updating to the newest version of the Sanity CLI and learn more about usage and migration paths in the documentation. With the update you will also get more features, including improved filters and sorting, as well as the ability to deploy tagged versions of your GraphQL endpoints.

GraphQL is available for all plans, and you can upgrade by running the following in your command line:

npm i -g @sanity/cli && sanity upgrade

Of course there are also new features!

Sorting, and filtering, for most things!

The beta version had limited field options when it came to filters, and sorting. So we made sure to improve those. If you want to get to a post by its slug or sort a product by its price, that’s totally doable. You can also filter and sort by nested values and with different boolean operators. As you would expect to be able to.

{
  allBook(
    where: {
      author: { name: { matches: "Gibson" } }
      publishYear: { gt: "2013" }
    }
    sort: { publishYear: ASC }
  ) {
    title
    publishYear
    author {
      name
    }
  }
}

{
  "allBook": [
    {
      "title": "The Peripheral",
      "year": 2014,
      "author": {
        "name": "William Gibson"
      }
    },
    {
      "title": "Agency",
      "year": 2019,
      "author": {
        "name": "William Gibson"
      }
    }
  ]
}

What! _ ?!

If you inspect the schema for the new version, you’ll notice an underscore of the type DocumentFilter. We studied most of the other automatically generated GraphQL APIs out there and saw a lot of different approaches. Our concern is getting in the way between you and what you want to do. We used the underscore because it is an invalid field name for Sanity’s content backend, and will never come in conflict with any of your content type names. We did look for prior art but soon realized that most vendors of automatically generated GraphQL APIs do this somewhat differently, and they will not always guarantee you against collisions between field names and filters.

Behind the underscore, you can filter documents based on what references them. For example, “give me all documents that reference the product with this ID”. You can also filter out all drafts if you happen to make an authenticated request with access to those.

{
  allBook(where:{
    _: { references: "0e8c6c52-7ebb-4a9c-8212-d8ff052bd162" } }
    limit: 1
  ) {
    title
    author {
      _id
      name
    }
  }
}

{
  "allBook": [
    {
      "title": "Agency",
      "year": 2014,
      "author": {
        "_id": "0e8c6c52-7ebb-4a9c-8212-d8ff052bd162",
        "name": "William Gibson"
      }
    }
  ]
}

Stay stable with tagged versions

The Sanity CLI will now warn you if you try to deploy breaking changes in your schemas. If you are not ready to adjust your queries in production, you can now deploy a new tagged version. This means you can run different endpoints with different subsets of your schemas at once. Or if you want to version your schemas, that’s a possibility too. We reasoned that the point with GraphQL is to have stable and predictable APIs, and not something that automatically changes whenever you’re experimenting with your content model or the like. We have also updated our source plugins for Gatsby and Gridsome to support tagged APIs.

GraphQL, powered by GROQ

Sanity’s primary query APIs is powered by GROQ. And people do sometimes ask us if we will support both GROQ and GraphQL going forward. The answer is an unequivical “yes”, we will support both because we don’t see these as opposed to each other. In fact, GROQ is what powers the GraphQL APIs (and it’s doing a great job of it as well). While GraphQL is more of a pattern for how to design an API, GROQ is an actual query language. You can in a way compare GraphQL to RESTful, and GROQ to SQL. We will continue developing both offers, and we look forward to learning what you will use them for.