Learn how to use GraphQL in Orchard Core CMS Query Orchard Core CMS Website content using GraphQL.

GraphQL in Orchard Core CMS is Perfect for Headless CMS Scenarios

Recently I mentioned using Orchard Core CMS as a Full CMS, Decoupled CMS, and Headless CMS. As a Headless CMS, the front-end of the website and client is completely separated from Orchard Core CMS and uses an API to access the content. As an Orchard Core CMS developer you are free to develop your own API, but Orchard Core CMS supports GraphQL out-of-the-box, which offers a very rich experience when querying data from Orchard Core CMS.

GraphQL and GraphiQL in Orchard Core CMS

Using GraphQL in Orchard Core CMS is almost too easy :) It's a feature that is typically disabled by default, so you enable it from the backend by navigating to Configuration -> Features. Once you enable GraphQL, you will see a GraphiQL menu option under the Configuration menu.

GraphiQL is an interactive in-browser GraphQL IDE. It is a developer tool that helps you create queries and explore your website's schema. I'm not going to blast you with images from within Orchard Core CMS, but do yourself a favor and enable GraphQL and explore the contents of your Orchard Core CMS Website using GraphiQL.

GraphiQL has an explorer that provides an interactive tree view of your Orchard Core CMS contents, allowing you to choose various Content Types, Content Parts, and Fields to query data in the CMS. As you choose the information to query from the tree view it builds the query text for you in real-time, which you can see in the query pane. If you wish to learn more about the content and relationships, you can view the documentation pane which provides help as it pertains to your Orchard Core CMS Website. Run the GraphQL query at anytime and you will see the data returned from the query.

Example Orchard Core CMS GraphQL Query

That's a lot to take in if you're both new to Orchard Core CMS and GraphQL, so here is an example query using the built-in Blog Theme that ships with Orchard Core CMS. The Blog Recipe only creates 1 blog post, so I went ahead and cloned it a couple of times, changing the Title, Subtitle, Categories, and Tags.

The data returned is not that important, but I did want to show an example of a GraphQL query that could be used to return the top 5 most recent blog posts published to the Orchard Core CMS website. This is something you might want to do if you have a blog and are running Orchard Core CMS as a Headless CMS. Maybe the front-end uses Angular, React, or Vue and you want to display the most recent blog posts stored in the Orchard Core CMS backend.

GraphiQL IDE in Orchard Core CMS for creating GraphQL queries.

The query might look a little complicated to create by hand, but you can easily create this query by exploring the schema in the GraphiQL explorer. I think it's self-explanatory. I'm querying for the top 5 most recent, published blog posts by publish date. For each blog post, I want it's path, title, subtitle, image, body, category, and tags. The body of each post is written in Markdown, but I specifically request the HTML. The category and tags use the Taxonomy Module in Orchard Core CMS and I'm requesting each taxonomy term's title.

Below are the results of the GraphQL query. I removed the HTML and collapsed 2 of the blog posts for brevity. If you spend a few hours using GraphiQL within Orchard Core CMS to explore your website's schema, you will become a GraphQL querying Ninja! Anytime you don't understand something just open up the GraphiQL documentation pane.

GraphQL Query in Orchard Core CMS

GraphQL Api in Orchard Core CMS

Once you familiarize yourself with GraphQL in Orchard Core CMS using GraphiQL, you'll want to retrieve this same data externally. Again, I'm thinking about the scenario where I'm using Orchard Core CMS as a Headless CMS and querying its contents remotely.

The simplest way to send a GraphQL query to Orchard Core CMS is via a REST Client to the GraphQL API in Orchard Core CMS. Pick your tool of choice. I typically use cURL or the REST Client extension in Visual Studio Code during presentations and training. Once you install the extension you can query the Orchard Core CMS website as shown below. The results are the same as shown above when using GraphiQL.

GraphQL REST Client in Visual Studio Code and Orchard Core CMS

GraphQL Permissions in Orchard Core

If you're running into troubles running GraphQL queries in Orchard Core, it's often a permissions problems. GraphQL has its own set of permissions that are assigned on a role-by-role basis. When you enable the GraphQL feature in Orchard Core you're logged in as an Administrator, which by default gives you the permission to execute GraphQL queries. However, if you're attempting to run these same queries using a different role, you may not have the proper permissions.

If you're using the GraphQL API from an external client, like Postman or the REST Client extension in Visual Studio Code, and have not been authenticated, you are attempting to run GraphQL queries using the Anonymous role, which by default does not have permissions to run queries. If you're just kicking the tires on GraphQL in Orchard Core and are not concerned with security, you can simply enable the Execute GraphQL permission for the Anonymous role. However, the recommended way to use the GraphQL API from an extenal client is to properly authenticate the client using the OpenID Connect features of Orchard Core.

GraphQL Permissions in Orchard Core

Conclusion

If you're developing websites using Orchard Core CMS as a Full CMS or Decoupled CMS, you probably won't need to concern yourself with GraphQL. However, if you're using Orchard Core CMS as a headless CMS, static website generator, or other way where external clients need to access the data remotely, the GraphQL support in Orchard Core CMS is brilliant!