GraphQL is basically a query language to retrieve and modify data on a server, and to subscribe to changes. Instead of making several different API calls, like in REST, a question is asked for all the data needed.
Typical use is where a web browser first retrieves and fills a web page with user-adapted information, then sends back changes based on user input and then continuously receives reports from the server when relevant information is changed.
The main unique feature is the query language that can request hierarchical data with relationships and get these in the selection delivered in the same structure as they are requested.
GraphQL was first developed by Facebook 2012 and was published in 2015 as open source. Development is ongoing, for example, schedules are added in January 2018.
What is GQL not?
GraphQL is not an individual implementation by or for clients or servers: There are, however, several implementations of GraphQL for multiple languages and platforms.
GraphQL is not a programming language: it contains a query language, a schema defining language and a type-defining / data-modeling language.
GraphQL vs. REST
As REST is a well-known architecture for web services, it is worthwhile to describe GraphQL visavi REST. GraphQL was developed by Facebook because REST was insufficient for their needs. The main differences have the emphasis on flexibility and efficient use of resources. There is also a big difference between where and when the biggest development effort needs to be done. Both REST and GraphQL can be used in applications other than web, but both have been developed primarily for that purpose.
When and for who is REST best?
- When the API is created for a known client: The client's data requirements are known and a tailor-made API streamlines development and usage.
- When the client or its developer needs a simple interface: The flexibility of the query language is not needed, but complicates for some developers or types of clients.
- When the client's need for data is controlled by one or few known parameters, such as date, sort order and number: The domain and its data can be so simple in nature that few and simple REST calls are optimal.
- When the client's need for data is not changed to its structure, for example, the same type of object is retrieved and most of its properties are used: Certain services and data are hardly rooted in standards or enforced and therefore have a low degree of change.
- When other data types than text need to be retrieved directly: GraphQL does not support other media types than text, such as images, video, audio, binary data, etc.
When is and for whom is GraphQL the best?
- When the client's selection of objects varies or is advanced, for example, selection through relationship between objects: The domain is complex to structure and has potentially high data turnover; active server and client part development may be inhibited by fixed APIs.
- When the client needs to do add-on questions to the server based on an earlier download: Because data has deep structure and / or relationships between them or then selection criteria are numerous or have complex conditions.
- When the client's needs for the parameters of the objects vary, for example, only a few parameters in large objects are needed: If data needs to be gathered from multiple types of objects, a REST API must be tailored to this to avoid unnecessary load on server and network.
Combining the two
A larger integration project or web service can of course fit into several of the above descriptions, so a combination of GraphQL and REST can be the best overall API solution.
To migrate between the two
Successful migration from REST to GraphQL requires some preliminary work in studying statistics from call and load on existing API. Which usage cases are listed under "When and for whom is XXX the best?" above, for example? Typical goals are to reduce the number of calls and complexity in processing on the client. An effective caching solution on the client may require identification of reusable objects and structures, and an adaptation to this in both data model and queries.
Successful migration from GraphQL to REST could be done if a usage study reveals that the client's needs really only sorts under "When and for who is REST best?" above. However, since a GraphQL solution has the highest cost at the beginning of development, such migration seems to be hard-motivated.
Publishing GraphQL APIs
To document GraphQL
With the introduction of GraphQL Schema Definition Language (SDL), the API can be visualized and viewed easier. There are several tools for graphically visualizing these, including interactive:
The question language also supports the demand for the schedule.
Analysis and statistics
For the collection and analysis of more than basic information such as the number of calls, call rate per client datasets överförsda, public server load and so on requires that the server that implements GraphQL has special support for detailed analysis and statistics, similar to database servers.
Implementations for clients
React is a library for building user interfaces, underlying Apollo and Relay / Relay Modern.
Deployments for servers
MuleSoft's Anypoint Exchange supports GraphQL.
A good and comprehensive review of GraphQL's many aspects can be found at How To GraphQL https://www.howtographql.com/