From 3ae7db70d24873c724465fe126393b372c1ca7ba Mon Sep 17 00:00:00 2001 From: VangoCode Date: Tue, 21 Nov 2023 19:00:27 -0500 Subject: [PATCH 1/9] Create GraphQL_VS_REST.md --- Topics/Development_Process/GraphQL_VS_REST.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 Topics/Development_Process/GraphQL_VS_REST.md diff --git a/Topics/Development_Process/GraphQL_VS_REST.md b/Topics/Development_Process/GraphQL_VS_REST.md new file mode 100644 index 000000000..e69de29bb From 9278aa4c23e667532c1713eee7c1c19083d258ed Mon Sep 17 00:00:00 2001 From: VangoCode Date: Tue, 21 Nov 2023 19:06:29 -0500 Subject: [PATCH 2/9] add structure for graphql vs rest document --- Topics/Development_Process.md | 3 +++ Topics/Development_Process/GraphQL_VS_REST.md | 17 +++++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/Topics/Development_Process.md b/Topics/Development_Process.md index f0efa913a..6f008b3b7 100644 --- a/Topics/Development_Process.md +++ b/Topics/Development_Process.md @@ -20,6 +20,9 @@ ## URL Sanitization ### [URL Sanitization](./Development_Process/URL_Sanitization.md) +## Design Decisions +### [GraphQL vs. REST: Which API type to use?](./Development_Process/GraphQL_VS_REST.md) + ## SOLID PRINCIPLES: SOLID is a mnemonic acronym that represents a set of five very important software development principles which lead to code that is easier to read, maintain, and extend, leading to higher-quality software that is easier to evolve over time. diff --git a/Topics/Development_Process/GraphQL_VS_REST.md b/Topics/Development_Process/GraphQL_VS_REST.md index e69de29bb..ab90bbc51 100644 --- a/Topics/Development_Process/GraphQL_VS_REST.md +++ b/Topics/Development_Process/GraphQL_VS_REST.md @@ -0,0 +1,17 @@ +# GraphQL and REST APIs +## Overview & Motivation +- What is an API +- Why do we need APIs +- Designing APIs + +## REST Overview + +## GraphQL Overview + +## When does REST make sense to use? + +## When does GraphQL make sense to use? + +## Quick reference for common uses + +## Additional Reading \ No newline at end of file From 5cee6377d60a58cdbe22dd00ad810f89ab56af2e Mon Sep 17 00:00:00 2001 From: VangoCode Date: Tue, 28 Nov 2023 15:50:39 -0500 Subject: [PATCH 3/9] write first draft aside from summary --- Topics/Development_Process/GraphQL_VS_REST.md | 69 +++++++++++++++++-- 1 file changed, 65 insertions(+), 4 deletions(-) diff --git a/Topics/Development_Process/GraphQL_VS_REST.md b/Topics/Development_Process/GraphQL_VS_REST.md index ab90bbc51..73d872b40 100644 --- a/Topics/Development_Process/GraphQL_VS_REST.md +++ b/Topics/Development_Process/GraphQL_VS_REST.md @@ -1,17 +1,78 @@ # GraphQL and REST APIs ## Overview & Motivation -- What is an API -- Why do we need APIs -- Designing APIs +### What is an API +An API is an **application programming interface**, or in simpler words, a way for two pieces of software to communicate with one another. + +On this page, we will refer to things called `endpoints`. These are basically access ways for our API - you use these endpoints to communicate with the software. + +### Why do we need APIs +Without APIs, there would be no way for software to communicate between one another. In fact, even within the same project, different components may have APIs between them to facilitate communication. Without APIs, software would never be able to interact with anything. Even something as simple as loading Google's webpage deals with many dozens of APIs without you knowing! + +### Designing APIs +In this article, we will specifically discuss APIs that deal with sending requests over the internet, which is a very special case of APIs. We will cover two special commonly used types of APIs: +1. REST +2. GraphQL + +On this page, you will learn about the differences between the two, and hopefully be able to make a confident decision on which one you need to use, based on your project requirements. ## REST Overview +A REST API is any API that follows the REST architecture. The implementation of it can be handled in many pre-existing libraries, so this page will focus on the important details: +1. In REST, you have to specify the `type` of the request you are sending when you call an API endpoint. + + Some common examples include `GET`, `POST`, `PUT`, and `DELETE`. Others exist, but these are the ones used most often. +2. REST is not specific; when you call an endpoint, you will get *all* of the data that endpoint can give, whether you like it or not. + + This can be ideal when you require a lot of data, but can also lead to larger than necessary load on your system if you have to call many API endpoints in quick succession. +3. Every difference type of request in REST has to be called to a different endpoint. For instance, if you want to `GET` all `Users` and `Cars` at the same time, with a typical REST API, you would need to send two seprate `GET` requests to a `/users` and `/cars` endpoint. + ## GraphQL Overview +GraphQL is difference from REST in the sense that it is not actually an API architecture. In fact, it is actually a `query language`, hence the QL in its name. This leads to a number of distinct characteristics that we will discuss: +1. In GraphQL there are only two types of requests: `Queries`, and `Mutations`. A query is used to get data, i.e, "query" some data. Everything else would be a mutation; creating, updating, or deleting data all mutate, and thus they are mutations. + + To follow proper GraphQL standards, any endpoint that only sends back data would fall under `query`. Any endpoint that changes data in any way would fall under `mutation`. +2. GraphQL is very specific; when you call an endpoint, you can request *exactly* what data you want, and you can send different structures of data, based on customizable `types`. +3. GraphQL only requires one endpoint. Usually, this is found at the `/graphql` URL on a webapp. Since GraphQL is a query language, whenever call the endpoint, you use the request body to specify your query. From this, you can define mutations and queries, and can in fact, get multiple pieces on data through one request. Using the same example from REST, you would only need to send one `/graphql` request, and just write both queries for data in the same request. This allows you to get the same amount of data using one request instead of two separate ones. + ## When does REST make sense to use? +REST makes the most sense if you deal with simple data, and you do not need to only get specific pieces of data; getting all of what you need is okay. In other words, if you're getting a User's data, for instance, you are okay with getting all of their data, instead of just their username for instance. ## When does GraphQL make sense to use? +GraphQL makes sense if you are dealing with quite complicated data, especially if it is large swaths of data where you might only need a specific chunk of it. It also makes sense if you need to get numerous different pieces of data at the same time, and want to do so efficiently. GraphQL is much faster than REST in terms of actual efficiency of getting data, but has a trade-off of a complex set up compared to REST. + ## Quick reference for common uses +In JavaScript, you can implement REST APIs through ExpressJS. Here is an example request, where you would call an already existing API request using fetch(). +```javascript +const response = await fetch("http://example.com/movies.json", { + method: "POST", + body: JSON.stringify({ + name: "Barbie", + director: "Greta Gerwig", + stars: [ + "Margot Robbie" + ] + }) +}); +``` + +You can implement GraphQL in JavaScript with the GraphQL library. Here is an example GraphQL query, where you would get the director of the Barbie movie, similarly to the above request. +```graphql +query { + getMovie(params: { + name: "Barbie" + }) + { director } +} +``` + +For more information on setting up and creating your own API through REST or GraphQL, you can visit their respective documentation here: +- https://graphql.org/graphql-js/ +- https://expressjs.com/en/starter/hello-world.html + +## Summary -## Additional Reading \ No newline at end of file +## Additional Reading +https://www.mulesoft.com/resources/api/what-is-an-api +https://www.redhat.com/en/topics/api/what-is-a-rest-api +https://www.ibm.com/topics/rest-apis +https://www.apollographql.com/blog/graphql/basics/what-is-graphql-introduction/ +https://aws.amazon.com/compare/the-difference-between-graphql-and-rest/ From dad1138377ce498d6dcf53abef2df15d47a07553 Mon Sep 17 00:00:00 2001 From: VangoCode Date: Tue, 28 Nov 2023 17:26:21 -0500 Subject: [PATCH 4/9] Complete GraphQL vs. REST page --- Topics/Development_Process/GraphQL_VS_REST.md | 30 ++++++++++++++----- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/Topics/Development_Process/GraphQL_VS_REST.md b/Topics/Development_Process/GraphQL_VS_REST.md index 73d872b40..0422c78f5 100644 --- a/Topics/Development_Process/GraphQL_VS_REST.md +++ b/Topics/Development_Process/GraphQL_VS_REST.md @@ -1,11 +1,25 @@ # GraphQL and REST APIs + +## Table of Contents +1. [Overview & Motivation](#overview--motivation) + - [What is an API?](#what-is-an-api) + - [Why do we need APIs?](#why-do-we-need-apis) + - [Designing APIs](#designing-apis) +2. [REST Overview](#rest-overview) +3. [GraphQL Overview](#graphql-overview) +4. [When does REST make sense to use?](#when-does-rest-make-sense-to-use) +5. [When does GraphQL make sense to use?](#when-does-graphql-make-sense-to-use) +6. [Quick Reference](#quick-reference-for-common-uses) +7. [Summary](#summary) +8. [Additional Readings](#additional-reading) + ## Overview & Motivation -### What is an API +### What is an API? An API is an **application programming interface**, or in simpler words, a way for two pieces of software to communicate with one another. On this page, we will refer to things called `endpoints`. These are basically access ways for our API - you use these endpoints to communicate with the software. -### Why do we need APIs +### Why do we need APIs? Without APIs, there would be no way for software to communicate between one another. In fact, even within the same project, different components may have APIs between them to facilitate communication. Without APIs, software would never be able to interact with anything. Even something as simple as loading Google's webpage deals with many dozens of APIs without you knowing! ### Designing APIs @@ -69,10 +83,12 @@ For more information on setting up and creating your own API through REST or Gra - https://expressjs.com/en/starter/hello-world.html ## Summary +In summary, there are many similar uses for GraphQL and REST. They can both accomplish the same things, but depending on your data structure, one would be better in terms of efficiency and complexity of development. GraphQL requires a lot more boilerplate code, and needs types and queries set up, while REST's setup just requires a few lines defining some simple endpoints. + ## Additional Reading -https://www.mulesoft.com/resources/api/what-is-an-api -https://www.redhat.com/en/topics/api/what-is-a-rest-api -https://www.ibm.com/topics/rest-apis -https://www.apollographql.com/blog/graphql/basics/what-is-graphql-introduction/ -https://aws.amazon.com/compare/the-difference-between-graphql-and-rest/ +1. https://www.mulesoft.com/resources/api/what-is-an-api +2. https://www.redhat.com/en/topics/api/what-is-a-rest-api +3. https://www.ibm.com/topics/rest-apis +4. https://www.apollographql.com/blog/graphql/basics/what-is-graphql-introduction/ +5. https://aws.amazon.com/compare/the-difference-between-graphql-and-rest/ From 3159f058f993dd4ed207eeac8b9ebb6a14577636 Mon Sep 17 00:00:00 2001 From: VangoCode Date: Wed, 29 Nov 2023 00:12:09 -0500 Subject: [PATCH 5/9] Added examples of API and Endpoints --- Topics/Development_Process/GraphQL_VS_REST.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Topics/Development_Process/GraphQL_VS_REST.md b/Topics/Development_Process/GraphQL_VS_REST.md index 0422c78f5..fce8b0b32 100644 --- a/Topics/Development_Process/GraphQL_VS_REST.md +++ b/Topics/Development_Process/GraphQL_VS_REST.md @@ -15,9 +15,9 @@ ## Overview & Motivation ### What is an API? -An API is an **application programming interface**, or in simpler words, a way for two pieces of software to communicate with one another. +An API is an **application programming interface**, or in simpler words, a way for two pieces of software to communicate with one another. For example, every time you interact with Google's website, an API is being called in the background to get your search result data. -On this page, we will refer to things called `endpoints`. These are basically access ways for our API - you use these endpoints to communicate with the software. +On this page, we will refer to things called `endpoints`. These are basically access ways for our API - you use these endpoints to communicate with the software. For example, when you search something on Google, their `/search` API endpoint is used to access the actual search API. ### Why do we need APIs? Without APIs, there would be no way for software to communicate between one another. In fact, even within the same project, different components may have APIs between them to facilitate communication. Without APIs, software would never be able to interact with anything. Even something as simple as loading Google's webpage deals with many dozens of APIs without you knowing! From b6a4890920086c56dc80bf90cffb8dedb3db3bb2 Mon Sep 17 00:00:00 2001 From: VangoCode Date: Wed, 29 Nov 2023 00:19:59 -0500 Subject: [PATCH 6/9] improve clarity on the oversharing of REST APIs --- Topics/Development_Process/GraphQL_VS_REST.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Topics/Development_Process/GraphQL_VS_REST.md b/Topics/Development_Process/GraphQL_VS_REST.md index fce8b0b32..8d1c18e5f 100644 --- a/Topics/Development_Process/GraphQL_VS_REST.md +++ b/Topics/Development_Process/GraphQL_VS_REST.md @@ -34,6 +34,7 @@ A REST API is any API that follows the REST architecture. The implementation of 1. In REST, you have to specify the `type` of the request you are sending when you call an API endpoint. + Some common examples include `GET`, `POST`, `PUT`, and `DELETE`. Others exist, but these are the ones used most often. 2. REST is not specific; when you call an endpoint, you will get *all* of the data that endpoint can give, whether you like it or not. + + For example, if you are trying to get the first name of a User, through REST you would send a GET request to a `/users` endpoint, which would give you the entire User object (i.e, more data than usual) and you would be required to parse the response and get the First Name. + This can be ideal when you require a lot of data, but can also lead to larger than necessary load on your system if you have to call many API endpoints in quick succession. 3. Every difference type of request in REST has to be called to a different endpoint. For instance, if you want to `GET` all `Users` and `Cars` at the same time, with a typical REST API, you would need to send two seprate `GET` requests to a `/users` and `/cars` endpoint. From b1d839ed8f6673e94513b9121e3bce45f55591ee Mon Sep 17 00:00:00 2001 From: VangoCode Date: Wed, 29 Nov 2023 00:22:32 -0500 Subject: [PATCH 7/9] fix spelling mistakes --- Topics/Development_Process/GraphQL_VS_REST.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Topics/Development_Process/GraphQL_VS_REST.md b/Topics/Development_Process/GraphQL_VS_REST.md index 8d1c18e5f..827e89b66 100644 --- a/Topics/Development_Process/GraphQL_VS_REST.md +++ b/Topics/Development_Process/GraphQL_VS_REST.md @@ -36,11 +36,11 @@ A REST API is any API that follows the REST architecture. The implementation of 2. REST is not specific; when you call an endpoint, you will get *all* of the data that endpoint can give, whether you like it or not. + For example, if you are trying to get the first name of a User, through REST you would send a GET request to a `/users` endpoint, which would give you the entire User object (i.e, more data than usual) and you would be required to parse the response and get the First Name. + This can be ideal when you require a lot of data, but can also lead to larger than necessary load on your system if you have to call many API endpoints in quick succession. -3. Every difference type of request in REST has to be called to a different endpoint. For instance, if you want to `GET` all `Users` and `Cars` at the same time, with a typical REST API, you would need to send two seprate `GET` requests to a `/users` and `/cars` endpoint. +3. Every different type of request in REST has to be called to a different endpoint. For instance, if you want to `GET` all `Users` and `Cars` at the same time, with a typical REST API, you would need to send two separate `GET` requests to a `/users` and `/cars` endpoint. ## GraphQL Overview -GraphQL is difference from REST in the sense that it is not actually an API architecture. In fact, it is actually a `query language`, hence the QL in its name. This leads to a number of distinct characteristics that we will discuss: +GraphQL is different from REST in the sense that it is not actually an API architecture. In fact, it is actually a `query language`, hence the QL in its name. This leads to a number of distinct characteristics that we will discuss: 1. In GraphQL there are only two types of requests: `Queries`, and `Mutations`. A query is used to get data, i.e, "query" some data. Everything else would be a mutation; creating, updating, or deleting data all mutate, and thus they are mutations. + To follow proper GraphQL standards, any endpoint that only sends back data would fall under `query`. Any endpoint that changes data in any way would fall under `mutation`. 2. GraphQL is very specific; when you call an endpoint, you can request *exactly* what data you want, and you can send different structures of data, based on customizable `types`. From 6ddc729bf7f0c054f6cf0ba61fd5eb8c0563c6ab Mon Sep 17 00:00:00 2001 From: VangoCode Date: Wed, 29 Nov 2023 00:32:30 -0500 Subject: [PATCH 8/9] Update additional reading section --- Topics/Development_Process/GraphQL_VS_REST.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Topics/Development_Process/GraphQL_VS_REST.md b/Topics/Development_Process/GraphQL_VS_REST.md index 827e89b66..e00fea85e 100644 --- a/Topics/Development_Process/GraphQL_VS_REST.md +++ b/Topics/Development_Process/GraphQL_VS_REST.md @@ -88,8 +88,9 @@ In summary, there are many similar uses for GraphQL and REST. They can both acco ## Additional Reading -1. https://www.mulesoft.com/resources/api/what-is-an-api -2. https://www.redhat.com/en/topics/api/what-is-a-rest-api -3. https://www.ibm.com/topics/rest-apis -4. https://www.apollographql.com/blog/graphql/basics/what-is-graphql-introduction/ -5. https://aws.amazon.com/compare/the-difference-between-graphql-and-rest/ +1. What is an API: https://www.mulesoft.com/resources/api/what-is-an-api +2. What is a REST API (1): https://www.redhat.com/en/topics/api/what-is-a-rest-api +3. What is a REST API (2): https://www.ibm.com/topics/rest-apis +4. What is GraphQL: https://www.apollographql.com/blog/graphql/basics/what-is-graphql-introduction/ +5. Differences: https://aws.amazon.com/compare/the-difference-between-graphql-and-rest/ +6. Performance: https://nordicapis.com/rest-vs-graphql-a-side-by-side-comparison/ \ No newline at end of file From 205d08aa9a995a5a1e5499675877ce9957dd0759 Mon Sep 17 00:00:00 2001 From: VangoCode Date: Wed, 29 Nov 2023 00:44:14 -0500 Subject: [PATCH 9/9] Add examples of multiple queries or mutations via graphql and rest --- Topics/Development_Process/GraphQL_VS_REST.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/Topics/Development_Process/GraphQL_VS_REST.md b/Topics/Development_Process/GraphQL_VS_REST.md index e00fea85e..c6bca5724 100644 --- a/Topics/Development_Process/GraphQL_VS_REST.md +++ b/Topics/Development_Process/GraphQL_VS_REST.md @@ -45,6 +45,7 @@ GraphQL is different from REST in the sense that it is not actually an API archi + To follow proper GraphQL standards, any endpoint that only sends back data would fall under `query`. Any endpoint that changes data in any way would fall under `mutation`. 2. GraphQL is very specific; when you call an endpoint, you can request *exactly* what data you want, and you can send different structures of data, based on customizable `types`. 3. GraphQL only requires one endpoint. Usually, this is found at the `/graphql` URL on a webapp. Since GraphQL is a query language, whenever call the endpoint, you use the request body to specify your query. From this, you can define mutations and queries, and can in fact, get multiple pieces on data through one request. Using the same example from REST, you would only need to send one `/graphql` request, and just write both queries for data in the same request. This allows you to get the same amount of data using one request instead of two separate ones. + + In GraphQL, you can send multiple queries, or multiple mutations via one request to the endpoint, meaning if you need to get many different pieces of data, or update multiple different data structures, it only requires one call. An example of this can be found in the [quick references](#quick-reference-for-common-uses) section. ## When does REST make sense to use? @@ -69,6 +70,17 @@ const response = await fetch("http://example.com/movies.json", { }); ``` +If you were using REST and want to get one movie, and get an actor's information, you would need to do this in two separate queries. + +```javascript +const response = await fetch("http://example.com/movies.json/Barbie", { + method: "GET" +}); +const response2 = await fetch("http://example.com/movies.json/MargotRobbie", { + method: "GET" +}); +``` + You can implement GraphQL in JavaScript with the GraphQL library. Here is an example GraphQL query, where you would get the director of the Barbie movie, similarly to the above request. ```graphql query { @@ -79,6 +91,22 @@ query { } ``` +Here is an additional example query, where you get a movie, and get an actor's information at the same time. You can do this in the same query. + +```graphql +query { + getMovie(params: { + name: "Barbie" + }) + { director } + getActor(params: { + name: "Margot Robbie" + }) + { birthday } +} + +``` + For more information on setting up and creating your own API through REST or GraphQL, you can visit their respective documentation here: - https://graphql.org/graphql-js/ - https://expressjs.com/en/starter/hello-world.html