Introduction

We are excited to present a proposal for a new approach to defining GraphQL APIs using the power of GROQ. This proposed solution aims to provide a flexible and customisable way for developers to create bespoke GraphQL APIs by authoring GraphQL schemas and using our custom schema directives to write GROQ expressions.

This document will walk you through the proposal and demonstrate how to build a simple GraphQL API using this new approach. Our goal is to address the limitations of the current GraphQL API by offering:

Custom Filtering: Apply filters on arrays and references.
Enhanced Projections: Use GROQ functions and expressions for custom field projections.
Improved Handling of Portable Text: Dereference content within block text.
Cross-Dataset References: Seamlessly integrate data across multiple datasets.

By empowering developers with more control over their API design, we aim to enhance the overall developer experience and provide feature-rich GraphQL APIs tailored to specific use cases.

We would greatly appreciate your feedback on this proposal to help us refine and improve the approach. Your insights on the overall developer experience, the effectiveness of the SDL approach with schema directives, and any other aspects are invaluable to us.

Your feedback will directly influence the future direction of our GraphQL offerings, ensuring they meet the needs of customers like yourself.

Thank you for your time and valuable input.

Background

Sanity’s current GraphQL API has the following limitations:

Generalized Schema: Built from your Sanity schema, it lacks customization options and is affected by any changes to the Sanity schema.
Limited Filtering: Missing support for filters on arrays and filtering references, reducing flexibility.
GROQ Parity: Missing features from GROQ, such as the count function.
Portable Text: Cannot dereference references in block content.