What is GraphQL?
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:
- Improved performance by reducing under and overfetching of data- ask for exactly the data you want, and it is returned as you want it
- Strongly typed, for more stable functionality
- Queries encoded on the client side, not the server side
- Now an open source spec since 2015
How Does GraphQL Work?
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.
What is a RESTful API?
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.
GraphQL vs REST
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.
- REST has issues with fetching, because the way a client gets data from a server involves REST requests hitting endpoints that return fixed data structures. GraphQL uses a strong schema definition to define the contracts between clients and endpoints.
- Frontend changes don't require backend changes with GraphQL, because the data needs have already been mapped in the schema. Frontend can make changes based on customer feedback without needing backend changes.
- As soon as a change is made in a web service's frontend, the data requirements of the backend have changed. Teams can define the schema when they begin a project (in GraphQL Schema Definition Language) so the frontend and backend teams can work separately, knowing the exact data structure as defined in the schema.
- GraphQL APIs typically only expose a single endpoint, with a completely flexible data structure that lets the client decide what data is actually needed. REST APIs load data from endpoints with a defined structure of the information that it returns.
- The issues GraphQL faces are mostly due to it being a young technology possessing a steep learning curve, and being potential overkill for simpler API solutions. It also has some backend shortcomings and difficulties in caching.
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.