REST APIs solved many problems related to SOAP APIs as web development grew. REST APIs were faster, accepted formats like JSON in addition to XML, and were stateless. As time has passed and REST became ubiquitous for APIs, engineers began noticing some eccentricities of REST. One of these was GET requests overfetching or underfetching data. With the standard GET API call, you access a single resource/entity, and you can't ask for just one field- you get the whole resource in the response. The minds at Facebook came up with a solution called GraphQL that used strongly typed schema instead of endpoints to organize data. This might seem like overengineering, but if you consider billions of people scrolling Facebook on mobile phones, potentially connected to satellite networks, this resource overheard was adding up. In this article, we will learn about GraphQL and REST, what their differences are, and what the future of API requests might look like.
GraphQL started its life at Facebook as a solution to problems with REST API design. It is a query language for fetching data, meant to solve problems with REST. GraphQL offers:
In a GraphQL query, the client needs to send more information to the server to express its data needs than with REST, but can get exactly what they're looking for. This is called a query. A basic GraphQL POST request looks like this:
Here we are querying a server for the field called team and its subfields like team and name. GraphQL allows us to define what we're looking for and structure the response we will receive, so we don't get a bunch of fields we don't need in one big JSON file necessitating pagination or repeat requests. We also have the benefit of communicating via one endpoint, instead of launching multiple requests to multiple endpoints. How does GraphQL do this?
A GraphQL schema is the backbone of every GraphQL API. It clearly defines the operations supported by the API and lets the client define what they're looking for. The schema is written in the GraphQL Schema Definition Language and defines the schema your API will use in the `GraphQLSchema` object.
Finally, the GraphQL resolvers convert GraphQL operations into data by resolving the query into data. Each resolver knows how to fetch the data for its field. To gather data, a GraphQL server invokes all the resolver functions for the fields specified in the query.
A RESTful API is an acronym for Representational State Transfer. REST is an architectural style which defines a set of architectural constraints for stateless communication between Application Programming Interfaces, or APIs. It is not a standard, so it allows developers some flexibility, but it acts as a mediator between users, clients, and resources. REST has become ubiquitous in API programming because it emphasizes scalability and greater sociability, while its predecessor SOAP was a highly-structured protocol that required XML.
At the heart of RESTful APIs is the contract between client and server. This contract defines what the API will do and what kind of requests and responses it will issue. In some ways it is the machine and human readable documentation of the API. If you call the API, you must do so in a way that it understands, and you must be able to accept its responses, also. An example of an API contract can be seen here. You can see the APIs URLs, verbs, HTTP responses, and contract statuses- all the rules of interacting with this API are defined in the contract. For more on contracts, check out the Open API spec.
REST is an API architecture style that facilitates HTTP connections, while GraphQL is an API querying language. REST architectures expose data through multiple endpoints, while GraphQL exposes only one endpoint. GraphQL accepts an information query from a client via this endpoint, and delivers that information from its flexible data architecture. The important distinction here is the client is defining what they are looking for, and structuring how they want to get it back.
GraphQL was initially popular with React developers, but has grown in popularity in the web development space since it was open sourced by Facebook in 2015. What makes GraphQL so useful is that it specifies both sides of the equation in client/server API relationships with its strongly typed schema. This requires significant initial setup, and learning the GraphQL Schema Definition Language, but the trade-offs in functionality and speed are worth it for more complex use cases.