Faster CX development and integration with GraphQL

by Sandra Schroeter, Technical Product Marketing Manager at Magnolia
Dec 1, 2020 | 4 MIN

As one of its headless capabilities, Magnolia provides a flexible delivery endpoint API. REST endpoints provide JCR data as JSON decoupling content and delivery. There are two potential challenges with this approach to query data: the response format and maintenance effort.

When requesting data from a REST endpoint, the format of the data differs by endpoint. This means that developers have to learn each endpoint’s unique response format before processing the data.

REST endpoints also require maintenance. An endpoint needs updating every time the data model changes. Changes to the endpoint might also require an update of the code that consumes its content. This dependency can be a blocker in software development.

GraphQL offers a smarter way of querying data. By providing access to all data in its registry, GraphQL eliminates the need for endpoint configuration making software development faster.

Front-end developers are no longer blocked when a REST endpoint doesn’t deliver the exact content they need, and back-end developers don't need to update their endpoints constantly. The GraphQL standard also enables developers to start working with data without having to learn how a specific endpoint behaves.

Because developers can specify exactly which data they need, queries become portable and responses more predictable. Due to its standardized request and response formats, GraphQL is also becoming increasingly popular for integration, for example in tools like Gatsby and Stackbit.

An added benefit is a smaller result set saving memory and network resources.

This is why we are adding native GraphQL support to Magnolia.

What is GraphQL?

The “QL” in GraphQL stands for “query language”. It was developed by Facebook to provide a standardized method to query data that is agnostic to its source. This means that as long as the API speaks GraphQL, it doesn’t matter how the data is stored. GraphQL was open-sourced in 2015.

GraphQL APIs organize the data they manage in a GraphQL schema by type and field and provide functions for each. This is how you tell the API which data you need. GraphQL then retrieves and, if needed, aggregates the data for you. The response is delivered as JSON.

How is GraphQL implemented in Magnolia?

When using the POST method, the behavior differs per Content-Type header:

  • application/x-www-form-urlencoded: queries and variables are sent as POST parameters

  • application/json: queries and variables are sent as JSON in the body of the request

  • application/graphql: queries are sent directly in the body of the request

In the first version, you will be able to fetch Magnolia Content Types via the GraphQL API.

How are Content Types mapped to GraphQL types?

The model of a Content Type is used to automatically create a GraphQL type definition, which is stored in the GraphQL registry. The GraphQL type definition is updated instantly every time a Content Type is changed.

It couldn't be simpler: your content authors can enter and update content using the Content Type’s visual Content App, and front-end and integration developers can slice and dice the content in any way they want using GraphQL.

Head to Headless Report

Visual headless: 1,000 CMS users share their thoughts on the next level of content management and digital experience design.

Download now

How can I query Content Types?

Single items can be queried by ID and path:

{
  book(id: "9778077a-e0c6-4b9a-9375-baa6c5a06f4d") {
    title
  }
}

Multiple items can use paging, sorting, and filtering:

{
  books(limit: 4, offset: 1) {
    title
    year
  }
}

{
  books(sort: [TITLE_ASC, YEAR_DESC]) {
    title
    year
  }
}

Filtering supports the following operators, that may be combined using AND and OR:

  • =

  • <>

  • >

  • >=

  • <=

  • LIKE

{
  books(filter: "@title = 'Radical Candor'") {
    title
    year
  }
}

By using nested queries, references to Content Types are resolved automatically and allow data aggregation in a single request:

{
  genres(filter: "name = 'Leadership'" ) {
    name
    books {
      title
      authors {
        name
      }
    }
  }
}

Conclusion

Magnolia is expanding its headless capabilities further by adding a GraphQL API to query Content Types. Compared to using the delivery endpoint API, using GraphQL can be a lot more efficient because of its standardized request and response formats. GraphQL also removes blockers in software development by eliminating the need to constantly update endpoints.

Find out more about Magnolia’s GraphQL API in the documentation.

About the Author

Sandra started her career managing mission critical environments at Hewlett Packard and found her way into product marketing via PostgreSQL consultancy. Having worked in the area of customer experience over the past few years, Sandra is passionate about creating customer-friendly digital experiences. In her role at Magnolia, Sandra is responsible for value-based product messaging for a technical audience as well as technical content strategy.