Magento 2 API updates: New Query Language

We’ve already written about Magento 2 API so why to come back to the topic?

Well, it’s been over a year, and some changes are in. You’ve most likely learned about these changes from our Magento 2 news post. But today we will discuss the particular area – Magento 2 API and new ways to deal with it.

Magento API: what’s new?

Actually, a lot. Magento is a dynamic system with a vibrant community who steadily monitor Magento users and try their best to resolve the issues they face.

As far as Magento APIs are concerned, Magento decided to offer a viable alternative to REST architecture and SOAP protocol. It’s GraphQL, a specific query language developed by Facebook in 2012 and released to the public in 2015. What for? Magento community strives for more flexibility and efficiency, and GraphQL exceeds the latter 2 in both. Let’s consider some examples.

GraphQL vs. REST API and SOAP API: Key advantages

Perk #1 Improved targeting

Working with GraphQL, you can indicate what data you expect from the server and get exactly what you’ve asked for. Here’s an example.

Say, you need to get the price for the product with the SKU 24-MB05.

With REST API it works as follows:

And here is how it works with GraphQL:

As we can see, REST extracts a bunch of information totally irrelevant to the query, while GraphQL takes out only the needed data.

Perk #2. Improved performance

Extracting data with GraphQl often requires only 1 query, whereas the same operation with REST and SOAP needs several.

Say, we need to get the price for the product with SKU 24-MB05 and the email for the user with id 1.

How will we get it with REST?

Add the query for extracting the user 1 email to the query for extracting the price (above):

With REST, we get a lot of irrelevant info. And what happens with GraphQL?

Take a look:

We get exhaustive information without any “noise”.

As we can see, GraphQL reduces the number of queries to the server, which improves its performance. What does it mean to the user? The results will be delivered faster and lagging will be reduced to a minimum if not null.

Working with GraphQL

Step #1. The start

And here comes the 1st stumbling block. At the moment, a convenient interface (like Swagger for REST API) is not available for GraphQL. So to work with this tool, you’ll need to install ChromeiQL, a special Chrome extension. After the setup, click on the extension icon. You’ll get to this page:

Then input http://<magento-directory>/graphql into the Set Endpoint field:

Now you can set off. Unfortunately, the available methods are not shown here as in Swagger. So you’ll have to check the code. To find the available methods, you need to open Magento modules and find those that end in graph-ql:

Enter any module and find etc. directory and then – schema.graphqls. Now search for the block type Query {}. As here we use module-catalog-graph-ql, the available queries are products and category:

Step #2 GraphQL: queries with examples

The language supports basic 2 types of queries:

type Query for reading;

type Mutation for performing CRUD operations.

But how to write a query correctly? We provide a simple guide below.

GraphQL: how to write a query?

1.First of all, we have to detect the query name. To do so, just check schema.graphqls file and find type Query or type Mutation (depending on the query in question). Query names are located on the 1st level of nesting:

2. Now let’s decide what info we want to get. Let’s “hunt” for the products with prices exceeding 45.

So our query is products. Now we need to set up filters. So we look for the needed filter in ProductFilterInput:

3. Great . To add the filter, we need to save the structure as it is in the schema.graphqls file. Now the query looks like this:

4. Now we need to set up a new filter. This attribute is of the FilterTypeInput type. Let’s find the type then:

5. Way to go! Now we add it to the query:

6.Then we detect how to find the file name we need. As you remember, the extracted type is Products. Here it is:

7. Now we check page_info, total_count, filters, sort_fields.

The docs to these attributes show that they are not what we need. So we are left with items of the ProductInterface type.

About The Author

Mihail Shagoiko

Being a dedicated Amasty Developer, Mihail is absolutely sure that reasonable giveaways are guaranteed to boost sales. He manages such modules as Special Promotions, Free Gift, Gift Card and others. On his own time, Mihail loves reading fantasy and skiing in the mountains.