Skip to main content

About GraphQL

Overview​

Swan uses a GraphQL API, an API language that emerged in 2015 and quickly became an interesting alternative to REST or x-rpc. From GraphQL:

GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data. GraphQL isn't tied to any specific database or storage engine and is instead backed by your existing code and data.

Learning GraphQL

This page explains GraphQL concepts required to work with the Swan API. If you're new to GraphQL, consider reviewing the GraphQL documentation, or following this tutorial from How to GraphQL.

Advantages​

  1. Strongly typed, permitting a robust API contract between Swan and API consumers. It's easy for clients to generate code to consume Swan's API, and easy to test a smooth integration (with contract testing, for example).
  2. Resilience. By giving power back to API clients, GraphQL has created a new class of APIs that are especially resilient to evolution.
  3. Finer command over the data you wish to fetch or over the way you wish to batch their requests thanks to GraphQL's request capacity. The freedom you have to consume Swan's API will also help you analyze client behavior and better respond to their needs.
  4. Introspection System, which allows you to ask Swan's server about which queries the API supports. A new developer can easily refer to it as built-in documentation. Learn more about introspection.
  5. Community. GraphQL creators helped create a powerful community from the start. Consider Apollo and The Guild.
  6. Future oriented. GraphQL is forward-thinking. In the Golden Age of APIs, when everything seems to come from APIs, GraphQL creates meta-graphs consolidating multiple different suppliers. With a stable and sustainable model, Swan believes GraphQL is the future of APIs.

Building blocks​

The Swan schema is built from a few core pieces, each covered on its own page:

  • Schema: the overarching structure that defines the entire API.
  • Queries: read-only operations that fetch data (similar to GET).
  • Mutations: operations that make changes (similar to PUT/POST).
  • Types: the strongly-typed building blocks of the schema.