Jan 10, 2020 Update: Check out UB PWA Mega Menu v1.1.8, packed with a newly added service layer -- MegaMenuGraphQL that helps you build flexible mega menus on top of Magento PWA Studio. View details here.
The new GraphQL API turns out to be one of the major moves in Magento 2.3, as written in our first blog post. Originally, GraphQL is a query language developed internally by Facebook in 2012 and has introduced a new era in web development since it was publicly released in 2015.
Let’s explore the advantages of using GraphQL API over REST API and the current state of GraphQL API in Magento 2.
Why GraphQL API?
As you might know, GraphQL has become the main API to support PWA Studio functionality and other custom storefronts. Magento introduced a layer of GraphQL endpoints as a communication protocol with PWA based storefront since Magento 2.3.0. There are still some gaps in GraphQL API coverage (not 100% of the functionalities available in Magento 2 are fully prepared), however its capabilities have increased with each release cycle of Magento.
Here’s a few key points that provide a good glimpse of why GraphQL API could be an obvious choice against REST API in Magento 2 in the near future:
- A query language that allows to optimize the network utilization:
- Complete description of data: GraphQL provides a clean definition of the data available in your API through a schema. The schema describes the types (including any relationships between those types) and defines allowed GraphQL operations (Queries and Mutations) you can perform.
- Clients (instead of server) define how data is returned and what they get
- GraphQL allows to wrap all of your queries, mutations, and subscriptions in a single endpoint. You can get as much data as you want in a single request.
- Enables API evolution: there’s no need for API versioning like the case in REST. You can evolve your API with new types, queries, and mutations without the need to ship another version of your API.
- Loose coupling between the server and client: the server-side app can offer all information about what is available on its side, and the client-side app asks for part of it by performing GraphQL queries, or alters part of it using GraphQL mutations.
| GraphQL | REST | |
|---|---|---|
| Single endpoint | A lot of endpoints | Each resource in REST is represented by an endpoint which ends up with multiple endpoints in real-world applications. REST APIs always return a fixed structure, which in return causes the over-fetching and under-fetching information through REST APIs. |
| Clients decides how data is returned | Server side decides how data is returned | With GraphQL, clients can read (query) and write (mutation) data based on the schema. |
| Schema-based | Schema-less | Schema in GraphQL is a central location, where all the available data is described. |
The current state of GraphQL in Magento 2.3
As far as Magento APIs are concerned, Magento implemented GraphQL to provide an alternative to REST and SOAP web APIs for frontend development. GraphQL was first introduced with Magento 2.3.0, and GraphQL coverage has increased with every Magento release.
Taking a look at what is coming up in the public Roadmap, it’s clear that the foundation pieces of GraphQL API are in place, as illustrated in the screenshot below:
Magento 2 GraphQL API Roadmap (View full size image)
The maturity of GraphQL API in Magento 2
With the current rate of progress, even though there are still some gaps, we see GraphQL API as the obvious way to go now. Focusing on GraphQL endpoints can be a good starting point, as Jisse Reitsma, the founder of Yireo, noted in the 2nd Magazine issue: “And now that numerous endpoints have been added to Magento 2.3.2 (..), I would say that 90% of the needed functionality is there… And the other 10% that is not ready is easily built as well.”
The base implementation of GraphQL in Magento 2
There are some great articles on GraphQL implementation in Magento 2, so we are not going to explain it in depth here, but below is current GraphQL codebase in Magento 2 you can explore to get familiar with:
- The base implementation of GraphQL in the /magento/framework/ folder:
- …/magento/module-graph:
- …/magento/: Example of how core Magento functionalities can be extended to provide queries and mutations:
Creating a new endpoint is all about adding a schema.graphqls file in its etc/ directory (or extend upon existing schemas) and a PHP class implementing \Magento\Framework\GraphQl\Query\ResolverInterface.
In order to work with GraphQL queries, you can make use of the ChromeiQL extension -- a Google Chrome addon which allows to write, validate, and test GraphQL queries. If you already have the ChromeiQL extension installed, you can check the GraphQL endpoint on our PWA Studio demo by entering https://pwa.demo.ubertheme.com/graphql in the URL bar, then click Set endpoint.
The following image shows a sample query, its response, and the GraphQL browser:
Sample query endpoint at: https://pwa.demo.ubertheme.com/graphql
Conclusion
It is clear that GraphQL API together with PWA Studio is becoming more mature which is supposed to bring us an entirely new way to create storefronts for Magento 2. We would recommend you to start playing with GraphQL API, so you can get used to the new tech stacks in Magento 2.
For further information about GraphQL API, follow the link below:
- GraphQL overview: https://devdocs.magento.com/guides/v2.3/graphql
- GraphQL roadmap: https://github.com/magento/graphql-ce/wiki/Roadmap
