# GraphQL 簡介 / GraphQL v.s. RESTful APIs

> - **A query languge** for querying and mutating data in APIs
>
> - **A specification build upon HTTP**
> - **One single endpoint**, receiving and mutating data based on what query client send to this end point
> - query **specific, nested** data with **one request**
> - 繼 RESTful APIs 以後，更有效、更準確的一種前後端 API 溝通方式
> - work with any language

## 簡述



<br >

### Back-End
**type** system describe schema of your data


<br >

### Front-End
- consuming APIs with the power to explore and request the **exact data they need**


<br >

***

## GraphQL 與 RESTful APIs 比較

### RESTful APIs 的問題

#### underFETCHING

<img src="https://i.imgur.com/LyQuVzC.jpg" width="300px">
<img src="https://i.imgur.com/iKkAIE2.jpg" width="300px">

:arrow_up:
需要多組 data，client 端要做多次 request 才能得到所有需要的 data (fetching multiple URLs )

#### 舉例：[台北一日遊加上我的收藏 feature](https://www.taipeitoursite.com/cowork)

使用在首頁 RESTful api 需要 request 至少三次[台北一日遊] 新增我的收藏 feature 後時候，使用在首頁 RESTful api 需要 request 至少三次

1. 取得當前使用者登入資訊：`/api/user`
2. 取得景點資料： `/api/attractions`
3. 取得使用者已收藏的景點資料：`api/favorite`

#### overFETCHING


:arrow_up:
只需要一個 API 的一小部分 data，卻 fetch 了一大包 data

#### 舉例：台北一日遊 user api，或其他 user api

**`/api/user`**

<img src="https://i.imgur.com/0Sj4fvT.png" width="350px">

我們在大部分的頁面，只需要知道：user 是登入或登出的狀態，並不需要 email, 名稱...的
而且一個更大的網站，user api 可能包括註冊時間、上次登入時間、其他 user 的資訊等等的，非常多資料，讓這個 user api 在各個頁面可以通用，但實際上我們並不是在每個頁面都需要這麼多 user 的資料，不過每次都會 fetch 整包 data

( 用 RESTful api 的其中一個解法是，每個頁面都設計不同的 user api 符合該頁面使用，但這樣對於 BackEnd 會是非常大的負擔)

<br >

### GraphQL 的優勢

#### 1. 一次 client request 拿回頁面所有需要的 data
> 解決 RESTful api underFetching 的問題

#### 2. 根據不同畫面，拿不同的欄位資料
> 解決 RESTful api overFetching 的問題

#### 3. API 文件即時更新
> 不再需要類似 SwaggerHub 這樣的 api 規格文件，即時更新

### GraphQL 運作概念
(下次再補更詳細的實作方式，本次先簡介概念)


:arrow_up:
BackEnd 會去 resolve Front-end 傳來的`.gql` request，從 database 拿到資料以後，以 JSON 格式傳給前端

<br >


:arrow_up:
可以透過 GraphQL 的 explorer 工具，輕鬆直覺的做出想要 query 的 data 的 `.gql` ，Client 發送這個 `.gql` 的 request 給 Back-End，並且得到 Back-End resolve 這個 `.gql` 後回傳以 JSON 格式回傳的 response