- **Epistemic status:** #evergreen GraphQL is a query language that allows the client to structure the data it needs and perform [[CRUD]] operations based on the schema. It was made to get over some limitations of [[Representational State Transfer (REST)]] where if you required a lot of different data types you would have to make multiple calls. Initially, it was an internal project by Facebook (now known as Meta) in 2012 before being publicly released in 2015. The project was moved to the newly-established GraphQL Foundation on November 7, 2018, hosted by the Linux Foundation. To use GraphQL, you need to first define a schema of your data: ```graphql type Note { title: String created: String, updated: String, } ``` After the schema has been defined, you can then start requesting data: ```graphql { note(name: "GraphQL") { title, created, updated } } ``` The data when fetched will return specifically what you asked for: ```json { "note": { "title": "GraphQL", "created": "2022-04-28 09:34", "updated": "2022-05-03 08:37" } } ``` ## Reasons for using it ### Data fetching is easier than REST As stated above, [[Representational State Transfer (REST)]] typically requires the data to be gathered by multiple endpoints. The more specific it gets can lead to code that is hard to understand. An example of this is: ```bash GET api.example.com/users/123?include=friend.friend.name&friend.friend.ocupation=engineer ``` GraphQL you can send a single query to the server with the data requirements specified. The schema can maintain a record on the relationships between the data. The code is often more readable. An example of this is: ```graphql { user(id: 123) { friends { friends(job: "engineer") { name } } } } ``` Since with [[Representational State Transfer (REST)]] the client needs to query endpoints with fixed data structures, it can lead to over or under fetching: - **Over fetching data:** To request more data than the client needs. For example, a client requests all the notes in the database requiring only the title and the body, but the data schema has created, updated, author, etc. The response could contain all the data that would be useless for the client. - **Under fetching data:** The client will need to request data from other endpoints because the specified one does not contain all the data required. For example, we want to get all the notes from a specific author we first need to get all the authors to find the specific one and then query the notes based on an identifier of that author. ### Faster iterations When working on a new product or feature, every time the UI is changed it might mean that a [[Representational State Transfer (REST)]] endpoint might need to be refactored to account for these changes to reduce the amount of data being over or under fetched. GraphQL allows for flexibility since their data requirements can be determined on the client side. ### Schema & type system All the types are written down in a schema using the GraphQL schema definition language (SDL) serving as a contract between the client and server. This allows the front end and back end team to work separately after that schema has been defined. ## Reasons against ### Caching [[Representational State Transfer (REST)]] have caching built in due to the HTTP specification, meanwhile GraphQL due to being a single endpoint does not. The responsibility is switched to the developer to implement caching. ### Exposed to arbitrary requests Due to how GraphQL allows the flexibility for clients to specify the data they need this can become problematic since expensive operations cannot be controlled bringing server performance down or even a DDoS attack. ### Reduced monitoring Client errors in GraphQL get a `200 OK` response, while [[Representational State Transfer (REST)]] can return a `5xx` response due to the HTTP spec. This makes it hard to know when errors are happening for the client, and more tooling is required to monitor the [[Application Programming Interface (API)]]'s health. --- ## References - Gilling, Derric. “REST vs GraphQL APIs, the Good, the Bad, the Ugly.” REST vs GraphQL APIs, the Good, the Bad, the Ugly | Moesif Blog, May 27, 2019. <https://www.moesif.com/blog/technical/graphql/REST-vs-GraphQL-APIs-the-good-the-bad-the-ugly/>. - “GraphQL | A Query Language for Your API.” Accessed May 3, 2022. <https://graphql.org/>. - “GraphQL vs REST - A Comparison.” Accessed May 3, 2022. <https://www.howtographql.com/basics/1-graphql-is-the-better-rest/>. - “How to GraphQL - The Fullstack Tutorial for GraphQL.” Accessed May 3, 2022. <https://www.howtographql.com/>. - “So What’s This GraphQL Thing I Keep Hearing about?” Accessed May 3, 2022. <https://www.freecodecamp.org/news/so-whats-this-graphql-thing-i-keep-hearing-about-baf4d36c20cf/>. - Sridhar, Aditya. “What Is GraphQL and How to Use It.” Aditya’s Blog, December 23, 2018. <https://adityasridhar.com/posts/what-is-graphql-and-how-to-use-it>.