The GraphQL API

GraphQL is:

  • …a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.”.

    See GraphQL.org

  • …an open spec for a flexible API layer. Put GraphQL over your existing backends to build products faster than ever before…”.

    See Explore GraphQL.

  • “…a data query language and specification developed internally by Facebook in 2012 before being publicly open sourced in 2015. It provides an alternative to REST-based architectures with the purpose of increasing developer productivity and minimizing amounts of data transferred. GraphQL is used in production by hundreds of organizations of all sizes…”

    See GraphQL Foundation.

For information about the GraphQL API, see the following sections (amongst many other resources):

The GraphQL for AEM implementation is based on the standard GraphQL Java Library. See:

GraphQL Terminology

GraphQL uses the following:

See the (GraphQL.org) Introduction to GraphQL for comprehensive details, including the Best Practices.

GraphQL Query Types

With GraphQL you can perform queries to return either:

AEM provides capabilities to convert queries (both types) to Persisted Queries, that can be cached by Dispatcher and the CDN.

GraphQL Query Best Practices (Dispatcher and CDN)

The Persisted Queries are the recommended method to be used on publish instances as:

  • they are cached
  • they are managed centrally by AEM as a Cloud Service
NOTE
Usually there is no dispatcher/CDN on author, so there is no gain in using persisted queries there; apart from testing them.

GraphQL queries using POST requests are not recommended as they are not cached, so on a default instance the Dispatcher is configured to block such queries.

While GraphQL also supports GET requests, these can hit limits (for example, the length of the URL) that can be avoided using Persisted Queries.

See Enable caching of persisted queries for further details.

NOTE
To allow direct, and/or POST, queries in the Dispatcher you can ask your System Administrator to:
NOTE
The ability to perform direct queries may be deprecated at some point in the future.