Additional Information
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:
```
query {
team {
id name
}
}
"data": {
"team":[ {
"id": 1,
"name": "Avengers"
}
,
…
]
}
}
```
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.
