A request enables a client to communicate with a server using different methods, depending on the intent of the request. To access data, the GET method is used, while the POST method is generally used to request the server to make changes.

ScandiPWA makes use of the GraphQL query language implementation on Magento, which has the concept of queries to request data and mutations to request that the server change data.

To optimize the request/response process, the server implements a caching system that allows the result of some requests to be stored. Then, the stored content can be used to respond to identical requests that follow. This has some advantages and disadvantages that should be taken into consideration when choosing the type of request to make.

It's essential to understand the different places where the response can be cached, as well as how to bypass the cache and ensure that the request reaches the server.

ScandiPWA has a pattern for making GraphQL requests. This pattern involves creating a document that defines queries and mutations, and then using built-in functions to simplify and secure the process.

These functions allow you to easily access the response as an object with keys that have the same name as the queries and mutations defined in the request sent.

However, it is always possible for a request to fail, and properly catching the error is crucial to ensure everything continues to work as intended. It is a good practice to inform the user about the error and provide instructions on how to proceed. This approach leads to a better user experience, despite the presence of an error.

What is a request?

A request is a method for a client to communicate with a remote server. The server processes the request and sends the appropriate response.

Untitled

There are 2 main request types(methods) in the HTTP protocol:

What is a GraphQL request?

GraphQL is a query language that can be implemented on a server to allow the client to select precisely what it needs in the response (using queries) and also to instruct the server to make changes (using mutations).

<aside> ℹ️ This page presents a basic view of GraphQL, for more details, take a look at the official documentation.

</aside>

<aside> ⚠️ To these queries and mutations actually work, the server must implement them. You can learn more about how to work with resolvers in Magento 2 and implement these functionalities:

How to work with Resolvers?

</aside>

What is a GraphQL query?

In essence, a GraphQL query requests data. The below example shows a query and a possible response:

Query example:

query {
    s_wishlist {
        id
        items_count
        updated_at
    }
}

Response example

"data": {
    "wishlist": {
        "id": "10",
        "items_count": 3,
        "updated_at": "2023-08-07 14:00:20"
    }
}

Note that this defines a query s_wishlist, which indicates that the response should include the fields id, items_count, and updated_at. The response will exactly match this definition.

What is a GraphQL mutation?

GraphQL mutations allow you to request modifications to server-side data.

The following example illustrates a mutation defined by ScandiPWA called s_clearWishlist. This is used to communicate with the back end to clear the wishlist.

mutation {
    s_clearWishlist
}

What type of request to use?

When considering the main request methods and the possibilities of GraphQL, there are 3 scenarios to consider for determining the best type of request to use in ScandiPWA.

Untitled

<aside> ℹ️ Note that there is no option to choose the GraphQL mutation using the GET method. This is because passing data to be saved in the URL is considered a bad practice.

</aside>

How does ScandiPWA make requests?

ScandiPWA makes use of GraphQL queries and mutations to communicate with the Magento server.

Instead of hardcoding the GraphQL query and defining complex requests in the code, which would make it hard to maintain and extend. ScandiPWA has a pattern to allow defining query documents and functions to make the request:

ScandiPWA makes use of query documents to allow you to dynamically create a query and use it in other places.

query {
	fieldName {
		nestedField		
	}
}

import { Field } from 'Util/Query';

const exampleQuery = new Field('fieldName')
		.addFieldList([
		    'nestedField'
    ]);

Using a query document, you can define the left example query like in the right example.

Although it may seem easier to define queries as shown in the first example, using query documents has significant advantages for development. They allow queries or mutations to be more reusable and extensible through the use of plugins.

You can learn about working with query documents:

How to work with queries?

How does ScandiPWA make use of the query document?

ScandiPWA request helper functions are defined in util/Request, which allows you to easily make the request using the query document. There are 3 functions:

<aside> ⚠️ You should consider what type of request to use when using these functions.

</aside>

<aside> ℹ️ It is preferable to use await instead of .then(). Using await makes the code more extensible compared to using .then().

</aside>

<aside> ✅ You can define your requests either in dispatch functions or src/util directory!

</aside>

How to send a query using the GET method?

The executeGet function allows you to send a query in the request using the GET method.

Check the example:

import { prepareQuery } from 'Util/Query';
import { executeGet } from 'Util/Request';
import YouQueryClass from "../../query/YouQueryClass.query";

const CACHE_TTL = 86400; // this is one day in seconds

// ...
try {
    const data = await executeGet(
        prepareQuery(
            YouQueryClass.getSpecificQuery()
        ),
        'requestName',
        CACHE_TTL
    );
    // process data
} catch (error) {
    // handle request error
    console.error(error);
}
// ...

The executeGet function accepts 3 parameters:

Examples of use:

How to send a query using the POST method?

The fetchQuery function allows you to send a query in the request using the POST method. This function does not allow caching, making it the best option for queries that may contain confidential information.

Check the example:

import { fetchQuery } from 'Util/Request';
import YouQueryClass from "../../query/YouQueryClass.query";

// ...
try {
    const data = await fetchQuery(YouQueryClass.getSpecificQuery());
    // process data
} catch (error) {
    // handle request error
    console.error(error);
}
// ...