Have you ever been in a project where you have to consume multiple endpoints to fulfill one single view with data on your front end? It’s a challenge. In this post we will talk about this wonderful technology that came to make everything easier, better and faster. But before that, a recapitulation.
Brief History
Back in the day we used SOAP (Simple Object Access Protocol) this is a message protocol that allows distributed elements of an application to communicate; mostly based on a XML basis (a real pain). This changed in the 2000 when the true potential of Web APIs was recognized: a group of experts, led by Roy Fielding, invented REST and forever changed the API landscape.
REST is not a protocol or a standard, but rather a set of architectural principles based on resources. API developers can implement it in different ways.
When a request is sent through a RESTful API, it passes a representation of the state of the required resource to whoever requested it. The information is delivered via HTTP in one of these formats: JSON (Javascript Object Notation), HTML, XLT, or plain text. JSON is the most popular, since it can be understood by both machines and humans and is not dependent on any language.
For an API to be considered RESTful, it must meet the following criteria:
While the REST API must meet all of these parameters (and a few others), it is easier to use than a predefined protocol, such as SOAP, which has specific requirements, such as XML messaging and security and compliance operations integrated, which makes it slower and heavier.
Rather, REST is a set of guidelines that can be implemented as needed. For that reason, REST APIs are faster and lighter, and are ideal for web and mobile application development.
So, how does this become any better? you may ask. Introducing GraphQL.
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. It gives clients the power to ask for exactly what they need, which makes it a great fit for modern web and mobile apps. GraphQL was developed in 2012 at Facebook, like many other technologies that are shaking the Javascript world and by 2015 it was launched as open source. It takes advantage of REST APIs by exposing one single endpoint to which you send queries in a special query language syntax. The server responds to a query by providing a JSON object.
GraphQL has its own type system that’s used to define the schema of an API. This syntax is called, ironically, Schema Definition Language (SDL).
type book {
title: String!
author: Int!
price: Float!
}
In the example above we created a simple type called Book which has 3 fields: title, author and price. The ! sign means the field is required.
{
allBooks {
title
price
}
}
Example of a query sent to the gql server based on SDL. This query would return a list of objects in the shape that the query was requested:
{
“allBooks”: [
{“title”: “book 1”, “price”: 9.99},
{“title”: “book 2”, “price”: 5.99},
]
}
I'm currently working for Playboy (you can view a list of our clients here) here in ArkusNexus and we've faced this problem, we had a lot of data sources that needed to feed multiple front ends, some of them needing more data than others, so we chose (after a large analysis) to move all the development into a new tech stack and that has made everything easier. Some of the benefits are:
A single endpoint. GraphQL has only one endpoint, where you send all your queries. With a REST approach, you create multiple endpoints and use http verbs to distinguish read and write actions (get, post, put, delete, etc).
Tailored to your needs. With REST you cannot control what the server returns back to you; the API will usually return you much more information than what you need.
Access nested data resources. GraphQL allows to generate a lot less network calls, for example, to get an author’s information, you would need to make multiple request: first the book, GET http://myrestfulapi/books/:id (which will return a lot more information than what you really needed) then now that we have the author’s id GET http://myrestfulapi/authors/:id (which also will return a more information than what you needed!)
When data drives UI:
Use for client-driven development
Pros: Contract-driven, Instrospection, Relations, Types.
Conns: Not as ubiquitous as REST
When you leverage HTTP:
Use for Resourses
Pros: HTTP Client, Golden Standard, HTTP/2 Performance gains.
Conns: Over fetching / Under fetching.
Bottom line:
it depends on the use case and most importantly, good API design.
