Nowadays, many purchasing decisions are made using mobile devices. Therefore, providing a good user experience is associated with adapting the website / eCommerce system to mobile devices.
Among the various methods, PWA (Progressive Web App) is a trend that is currently developing very strongly in mobile technology. These applications load like regular websites, but their functioning is very similar to native applications. For example, they display notifications, work offline and in the background, and can use device functions (e.g., camera, geolocation, gesture navigation).
With this in mind, we decided to create a connection between Alokai – PWA frontend (previously Vue Storefront) and Sylius (eCommerce backend). The technical aspects of this connection are described below.
To go to the essence of the connection itself, we have to explain some things first. So, let’s start with the API.
API – explanation and types
API (Application Programming Interface) is a tool that allows systems to communicate with each other. Pretty general definition, right? To illustrate this better, let’s take an example of a restaurant:
You are a guest (client) and want to order a dish from the kitchen. However, you don’t have direct access there. So what do you do to order a meal? -Asking a waiter. The waiter is your API. You can ask him if the selected dish is available or ask for the details of it. The waiter will take your message to the kitchen (closed system) and get back to you with a ready meal or information- the API response.
Applications using the API can exchange data in various ways and various forms. Depending on these defined rules – an application may, for example:
- Download resources of another application that provides the API.
- Make changes by executing specific queries specified in the API.
- API can be open – accessible to everyone or secured, e.g., with a private key, JWT, OAuth 2.0
It all depends on what the specific API allows – it usually should be included in the documentation.
Let us now take a more technical example:
You have a fanpage on Facebook or Twitter where you publish some content.
You want to display the same content on your website. Rewriting all content will be tedious and time-consuming, so using the API connection is a good idea. Thanks to the connection via API, you can automatically ask a given website (whether it’s Facebook, Twitter, or anything else) if there are new posts. If a new post exists, you will download it and display it on your side.
The API can also work the other way around, and from your website, you can publish the same post on Facebook or Twitter.
The API is a bridge connecting various applications and enabling data exchange.
We can list several types of Web API technologies:
- REST architecture
- SOAP protocol
- GraphQL query language
GraphQL
GraphQL is the query language for the API. In 2012, Facebook started it as an internal project. It arose from the need for greater flexibility and efficiency in client-server communication. The main goal was to overcome the problems with downloading data from their native platform.
In 2015, Facebook released GraphQL on an open-source license. GraphQL has gained popularity in the last few years and has become a powerful alternative to REST. Many companies such as Facebook, PayPal, and Twitter use GraphQL in their products.
Google trends:
GraphQL as a complement to the REST API
The HTTP endpoint in the REST API is the URL or URI to which the requests are sent and usually looks like this:
HTTP is the acronym for Hypertext Transfer Protocol. It is designed to ensure communication between clients and servers. HTTP acts as a request-response protocol between the client and server.
- GET is used to request data from a specific resource.
- POST is used to send data to the API server for resource creation.
- PUT is used to send data to an API to update a specific resource.
- PATCH is used to apply partial modifications to a resource.
- The DELETE method is used to delete the specified resource.
When using GraphQL, we have one endpoint.
Where the content of the query might look like this:
Each field of the above query will be returned as a key with a value in the response in JSON format. It means that the query defines the amount and format of data in the response. The client will receive exactly what he needs. This flexibility is GraphQL’s most significant advantage.
REST responses usually return all possible information, which is often not needed.
In the traditional approach, to display all the details we want, we often have to make many queries to properly aggregate the data and display the view of, for example, a single product.
Of course, many queries can significantly slow down the application’s operation and require more data transferred via the link. GraphQL deals with this problem very well and optimizes this part of the client-server connection.
When writing an API, especially the public one, it is obligatory to have documentation. It allows other programmers (who intend to use our solution) to know exactly what operations they can use and what types of data they can return.
It smoothly leads us to another advantage of GraphQL: strong typing. In contrast to the classic REST API, in which it is often not known what type to expect in the response from the server – although the documentation may say one thing – it is sometimes not updated.
Thanks to strong typing, GraphQL, in conjunction with the API Platform on which the Plugin is based, always returns documentation automatically generated based on the definitions of operations on the server.
At this point, it is worth mentioning API versioning.
In the REST approach, with significant changes, a new version of the API is made available. Why? Because in this approach, we have no control over the returned data. Another version should be made available when changing the name, modifying the returned data, or their types.
GraphQL suggests in its tab about good practices that the API should evolve – even with the possible change of the name of a parameter, the client can use an alias during the query.
In addition to data inquiries, we can also clearly perform operations that reflect business operations very well. For example:
Remember that GraphQL only returns data in JSON format.
It means it cannot return files unless the file is base64 encoded. The same situation is with the upload. So instead, we can use GraphQL to return links to files that are, for example, in the S3 basket on AWS or anywhere else.
The simple conclusion is that GraphQL cannot often replace the entire API, but it is an excellent addition to the REST architecture.
GraphQL Pros
- Easier implementation for frontend developers
- Performance improvement
- Emphasis on supporting DDD – Domain-Driven Design (an approach to software development with an emphasis on defining system objects and components and their behavior in such a way that they faithfully reflect reality)
- Automatically generated documentation
GraphQL Cons
- It is the next layer of the application to be maintained
- API Platform is still in the experimental phase
What does the SyliusVueStorefront2 Plugin provide?
The plugin provides the basic methods required for the operation of the online store for the customer. However, the plugin does not provide any operations for the admin panel.
- Authorization by JWT
- Basic filtering of products and categories
- Viewing Categories and Products
- Change of data in the user account along with password modification and reset request
- User address management
- Submitting an order
- Adding and removing products from the basket
- Changing quantity with checking their availability
- Selecting a shipping/billing address from a pool of previously saved
- Adding a new shipping/billing address
- Adding a discount coupon
- Order approval
- Managing product reviews
- Viewing the order history as a logged-in user
- Filtering products by their attributes and prices
Summary
GraphQL doesn’t want to get rid of the REST API but acts as a complement to it. It is an additional application layer that needs to be developed, but the plugin offers simple ways to adapt individual actions to your needs. As a result, it increases efficiency, and thanks to its flexibility, it is easier to use for the client and develop for the API developer.
In conjunction with the Alokai, the plugin allows you to connect the front-end part of the store set on VSF2 with the Sylius backend on the vanilla-to-vanilla principle.
If you need help with this integration, do not hesitate to contact us!