GraphQl concept introduction
Restful is Great! But GraphQL is Better. — My Humble Opinion.
GraphQL will do to REST what JSON did to XML. — Samer Buna from Quora
GraphQl has been around for a while as one of Facebook’s first three carriages (along with Relay and React, which work seamlessly together), but has been used by surprisingly few people. As of the end of 2018, according to StateofJS, Although only 1/5 of the developers have used it, there are up to 62.5% of people who have heard of it and want to try it 😂 It really is the mainstream; Next, I’ll write a series of articles on GraphQl’s front and back ends and how it feels to use GraphQl, to fill in the gaps.
This series will use Python + Django + Graphene as the back-end server. Apollo serves as the front-end client.
1. What is GraphQl
Here’s what the authorities say:
GraphQl is both a query language for APIs and a runtime for your data queries.
GraphQl provides an easy-to-understand and complete description of the data in your API, allowing the client to get exactly what it needs without any redundancy.
It also makes the API easier to evolve over time and can be used to build powerful developer tools.
Let me summarize:
First, GraphQl is a query language similar to the RESTful standard. Their levels of functionality are similar (see chart below), but in practice and ideologically, they are two completely different forms.
RESTful asserts that “all data is a resource,” ideally: different requests correspond to a unique ID. Different data actions correspond to different HTTP methods.
GraphQl asserts that “all data is treated as data (tree),” and that different requests will correspond to the same HTTP address and also to the same HTTP method (POST). The different actions are determined by the operator. The overall experience will be more like an SQL Shell, where you ask for what you need and you won’t be shoved anything you don’t need.
Similar to RESTful, they are all just standards, and their implementations vary from product to product, and it’s normal not to fully implement all the features. But the main functionality and features are in all implementations. The other two have similar language support, and common languages have their own implementations.
In the following, I will make a relatively detailed comparison of the differences between the two. Since RESTful is a relatively general standard, I will not go into the details of RESTful below. If you are not familiar with RESTful standards, it is better to learn about them before continuing so that you can better understand them.
2. GraphQl versus RESTful data manipulation
2.1 the query
RESTful claims that all data is a resource, which means that you will need to request different kinds of data multiple times. For example, for a personal SPA-type blog like mine, you will probably request this content when you enter the home page (purely hypothetical, not real) :
// Some configuration class information: Such as configuration items, such as site title https://example.com/config/ / / side of the TAB bar https://example.com/tags/ file bar / / https://example.com/archives/ / / side The announcement info https://example.com/billboard/ / / article list https://example.com/articles/That’s the amount of information that a single page blog like this would have to request as soon as it got to the home page. Imagine the amount of information that would be requested on a highly concurrency, complex content structure site.
But with this in GraphQl, you only need to request it once, for example:
query {
config: {
key,
value,
}
tags: {
name,
}
archives: {
name,
}
billboard
articles {
id,
name,
description,
tags: {
name,
},
}
}The interface would then return something like this:
data: {
config: [
{
key: 'title',
value: 'xxx',
},
{
key: 'slogan',
value: 'xxx',
},
],
tags: ['Go', 'Java', 'Javascript'],
archives: ['2011', '2012', '2013'],
billboard: 'XXX XXX XXX',
articles: [
{
id: 1,
name: 'some name',
description: 'XX XX XXX',
tags: ['tag1', 'tag2'],
},
{
id: 2,
name: 'some name',
description: 'XX XX XXX',
tags: ['tag1', 'tag2'],
},
{
id: 3,
name: 'some name',
description: 'XX XX XXX',
tags: ['tag1', 'tag2'],
},
],
}You can see that the returned content of the interface is a JSON data returned exactly according to the content and field you requested. Keeping the structure you request, you can make up the tree you want, and the back end doesn’t have to write some weird interface to fill in the implementation conflict between business and development for each of your specific requirements.
Another is that in some cases, requests made in a RESTful manner may need to be split, meaning that events that could have been requested in parallel need to be serialized because of RESTful standards.
Let’s say we want to get other similar articles under the category that the current article is associated with, and display them in the margins.
You might ask first:
https://example.com/article/1/After getting the corresponding article classification, then request:
https://example.com/article/?category=graphql&is_recommend=trueThen you can render the full page content. All of this can be avoided in GraphQl.
For data associations, common SQL foreign keys and associations can also be directly mapped to subitems. For example, the tags in “articles” in Example 1 above are usually connected to different tables as foreign keys of data. In GraphQl, it can be directly retrieved as subtrees.
All query operations are performed in GraphQl with the query operator. It can write numerous different request content, do not separate request multiple times. When you need to request the same content repeatedly, the front-end GraphQL client has automatic cache processing, can the current web page instance only to a certain content request behind once again the content will not directly use the cached information network requests again, of course you also can do it again.
2.2 change
In RESTful, we’re used to describing behavior with different HTTP methods, but in GraphQl, we use operators to indicate behavior.
The above query refers to the query operation, which corresponds to the SQL SELECT operation. What if you want to change it? We use mutation in GraphQL, which corresponds to UPDATE, INSERT, and DELETE in SQL. It looks like a mess at first, but it doesn’t feel that way when you actually use it. I can’t really boast about this part, though, because I personally feel that it’s more like putting something on the front that was originally done on the back end. It is used much like giving the front end a “back-end function”.
* All of the examples below are just for demonstration, not for actual writing, which is more rigorous
If we wanted to delete an article, we could do this:
mutation {
deleteArticle(id: "some ID") {}
}If you want to add an article:
mutation {
createArticle(
title: "some title",
content: "some content",
) {
id,
title,
content,
}
}Modification operations are similar to additions and will not be described again.
While it may look sparse and haptic, it actually gives developers more freedom. Convenient custom behavior. Another thing worth mentioning is that before the actual Mutation, after a Mutation operation is called, it will automatically check the type of the input parameter in the front-end code, which is similar to the compilation of static language. If there is an error in the input parameter, it will automatically report an error and give an error message at the location of the error. An HTTP request to change the operation is made only if the problem is solved. When it is passed to the back end, the back end does the validation again. I personally quite like that.
2.3 the subscription
Subscription is one of the more prominent features that traditional businesses often have, but RESTful doesn’t care about. Subscription in GraphQl does not seem to be fully supported in most implementations at the moment. The general idea is that when you subscribe to something on the front end, the server will actively notify the front end of any changes to the content on the back end, thus triggering UI logic or actions, etc. Currently this feature seems to be unsupported or not fully supported by most implementations. And it seems like most of the time you have to rely on long links or polling to do it. Still, it’s very promising, because what it does is it lets you subscribe to arbitrary data, rather than having the back end make a dedicated interface for a particular content, as the traditional implementation would have it.
A classic application scenarios such as: when you open an article, this article comments sent a subscription operation, at this time if someone while you see the article on articles such as a new comment or reply, corresponding changes will be by the backend actively pushed to the front, so that you can live to see the latest comments.
Subscription corresponds to the Subscription operator in GraphQl. Similar to mutation.
If anyone is familiar with it, please let me know. I’m not familiar with this area and I don’t know much about it.
2.4 the paging
Traditional RESTful uses spacing, which means that after a fixed spacing is set, the content of any page can be inferred from the spacing and the current page number.
GraphQl is a bit more of a pointer pager, where no matter what element you’re currently on, you ask for a given number of requests forward or backward, using the current point as a pointer. It has the disadvantage of not being able to deduce the contents of any page in the current position like the spacing method, but it has the advantage that you don’t care about any other information at all, always using the current point as a pointer to seamlessly scale back or forward at will.
RESTful will be more in line with the traditional desktop indexed interactive experience habits. An approach like GraphQl’s is more convenient in more modern Web interactions, such as waterfall flows, applets, and the auto-loading of slides in native applications.
PS: GraphQL can also be used for spacing, which we’ll discuss later in this article.
3. Advantages of GraphQl over RESTful
3.1 Interface version management
The standard management in RESTful is declared in different link entries, such as:
https://v1.example.com/
https://example.com/v1/In GraphQl’s world, there are no different entrances, and interface iterations can be seamless because the front end itself is the source of the different queries, and the front end is not constrained by the back end.
3.2 Clearer and more transparent data structures and more robust interfaces
As I said above, in practice, both the front and back ends have strongly typed parameter validations, so it’s relatively error-prone, and! It greatly reduces the possibility of other hidden errors. Such as a logic error caused by a back-end changing something in an interface and forgetting to tell the front end. These extremely common problems are not likely to occur in GraphQl.
3.3 Better caching system
As I mentioned in the Queries section above, GraphQl’s client comes with a built-in caching system to further reduce request consumption. You can turn this feature off if you don’t want it.
3.4 Front-end friendly development experience
As mentioned above, what you need is determined by the front end. In business where strong associations are needed, GraphQl can look up associations indefinitely, eliminating a lot of asynchronous syntax on the front end and greatly avoiding the Promise or Callback hell. In addition, in some back-end languages, such as Python, fields are usually named for underscores by convention. But in JavaScript, the hump naming is much more common, and since the data is coming back from the back end, you can’t avoid making the front end code look ugly with all sorts of different naming methods; You may say that we can do name cleaning after we get the data, but this will increase the time complexity and reduce the maintainability of the code, which is not desirable in any case. But!!! This problem doesn’t exist in GraphQl (or, strictly speaking, in the technology stack I use). Because in Graphene, it will automatically convert the naming method of the returned data, the front end is humped, the back end is underlined with no interference.
3.5 Rigorous development experience and more obvious error reporting mechanism
Because the input and output of GraphQl are defined based on Schema, the calling methods and queries are all strongly typed input and output, which can locate the cause and location of errors more efficiently. If a client operation passes an incorrect parameter, it will not even make a request and report the error directly to the client with the reason. If the argument was passed correctly but the server made an error, everything else in the same query will be returned correctly, except for the error that will be empty and a message field will be provided to explain why and where the error occurred.
The graph below shows the GraphQl V4 API for GitHub. You can see that the user’s query failed but the search data returned normally.
3.5 More convenient debugging process
In addition to the above very detailed error report, you can even dynamically Debug directly in the browser; The following is a Debug query for one of my own projects. You can see how the SQL statement of the current query was written, how long it took, whether it took too long, what parameters it took, the transaction ID, the transaction status, and a variety of other information.
(I will not show the specific SQL statement for security reasons)
3.6 Code is documentation
As you can see from the above images, GraphQl provides a dynamic interaction window within a web page, providing GraphQl with auto-completion, formatted queries, history, and other information. One of the most powerful is its interface documentation. Code-as-document information is very useful.
Here you can directly see how the whole tree structure is, and you can also see the clear class inheritance relationship (not shown in the figure). You can also see the detailed description of different query contents and parameter types, etc.
4. Weaknesses of GraphQl
Whatever it is, two things must have advantages and disadvantages in comparison. GraphQl has a number of advantages for developing a modern, complex Web service or site, but it also has significant disadvantages.
4.1 Performance overhead
Because GraphQl has its own hierarchical query, it is easy to have redundant queries, causing unnecessary query overhead.
Of course, a lot of this has to do with the backend framework you’re using, and I recommend a well-written article on Django called The N+1 Problem
4.2 Development without prompt
Although it does provide a very powerful debugging window in the web. But in the real world, the front-end doesn’t tell you what you’re writing in the IDE, and it’s easy to misspell, because the editor doesn’t know what you’re writing, it treats it as plain text at best, and it doesn’t format the content, so it’s a little uncomfortable in development.
4.3 Relatively few interface testing tools
RESTful has a long history and is widely used, so basically all interface tools on the list can support RESTful queries, but GraphQl can’t. I currently know of only Insomnia support, but it doesn’t support document parts very well. (Of course, the framework already provides great debugging tools.)
5. The GraphQl client is no better
It just depends on your foundation, there are two dominant companies in the market, one is Facebook’s own Relay, and the other is Apollo supported by the community.
Relay costs more to learn, just like when you just learned the basics of React and write some simple pages with React, you are suddenly asked to learn Redux ideas. Need to learn a new set of data management.
Compared with Apollo, it is more friendly. It supports JSX-style block writing and only uses its request function like Axios directly. It can also be compatible with Relay query writing, so the learning threshold is relatively low. The native state management is a complete replacement for Redux. True Axios + Redux
End of 6.
Both are standards and design guidelines; It is not objective to say that one is better than the other. But personally I can see a lot of advantages for GraphQl over RESTful. After all, Graphql itself is younger than RESTful, and it must have been created to solve most, if not all, of the problems left over from its predecessor.
The most important thing is that the two can be completely compatible. No one disturbs the other.
Finally, add more extended reading and learning links:
- Graphql – Chinese website
- How to Graphql – A learning site
- Rest VS GraphQL
- GraphQL or REST
- Is GraphQL a REST killer?