Skip to main content

Embracing GraphQL

Saleor was the first commerce platform to fully adopt GraphQL. We are strongly committed to the ecosystem and its philosophy.

Benefits of GraphQL​

Fine Control Over Data Fetching​

GraphQL allows a single request to cover as many or as few fields as needed. Multiple requests can be combined to fetch all the data at once, avoiding the cost of multiple network round-trips, or a single request can be split to defer fetching more costly data until it is needed.

This is especially useful in commerce, where the data models can get complex and implementers are often forced to compromise on the accuracy of modeling to combat the cost of fetching large structures. With GraphQL, you can accurately model your data and fetch only what you need, avoiding the problem of over-fetching (where a significant chunk of the data received is not useful to the client) and under-fetching (where important fields are missing from the initial response, so additional requests are needed).

Saleor takes this a step further by using GraphQL for all of its APIs, including webhook subscriptions. This allows external integrations to benefit from the same fine-grained control and flexibility as the storefronts, and can be used to control what data is shared with third-party applications.

Mature Ecosystem​

While REST is largely a set of conventions, GraphQL is a specification with a well-defined schema and type system. This allows for a much higher interoperability between different implementations and a more consistent developer experience.

The schema is self-documenting, including all the operations, and we believe it's much easier to tell checkoutCreate and checkoutComplete apart than it is to remember the nuances of POST, PATCH, and UPDATE in a particular endpoint's implementation.

Having a standardized schema allows for better tooling, so you can benefit from great IDE integrations, including auto-completion and query validation.

Strong Type System​

Each GraphQL API is defined by a schema that provides a strongly typed contract between the client and server. This allows for better tooling for developers, including code generation, static type checking, and visual query builders.

Those familiar with WSDL and OpenAPI will find themselves at home: the GraphQL schema is a more powerful and flexible alternative.

TypeScript developers will love the type safety that GraphQL provides when combined with automatic type generation.

Ease of Maintenance​

Since GraphQL queries explicitly list the fields they need, adding new fields to the API is a non-breaking change. The protocol also allows deprecating fields by marking them as deprecated in the schema, which allows IDE integrations and static analysis tools to warn developers that the codebase may need to be updated without breaking the already deployed systems.

The above features make it easy to evolve the API without breaking existing clients, at the same time removing the need for explicit versioning of the API. We find this to be very important in large deployments, where multiple codebases may interact with the same API but their release cycles cannot be aligned easily.

Common Misconceptions​

  • GraphQL is complex. Consuming GraphQL APIs is straightforward, and in many ways can provide a better developer experience than REST. Building GraphQL APIs requires experience, however as a user of Saleor you don't need to worry about that.

  • GraphQL is slow. GraphQL is just a query language and does not introduce any overhead. GraphQL is often faster than REST because it allows you to fetch all the data you need in a single request.

  • GraphQL is a database technology. GraphQL is a query language for APIs, it has no opinion on the underlying database or data source.