`#JavaScript` `#六角前端課程` `#學習筆記` `#骨力走傱`

## API 與 RESTful API
### API
> API（Application Programming Interface，應用程式介面）是一組定義不同軟體系統之間如何互動的規則和協定。

> 簡單來說，**API 的主要目的是調用某些功能或服務，而不需要重新去寫這些功能。這使得軟體開發變得更加高效**，並且能夠利用其他系統或服務提供的功能。

> 舉例，你（使用者）去餐廳用餐，告訴服務員（API）你想吃什麼，接著服務生（API）會轉達給廚師（後台系統），廚師（後台系統）會幫你處理好菜色，再透過服務員（API）將餐點端給你（使用者）。


### RESTful API
> RESTful API 是一種基於 HTTP 協議的 API 設計風格，通過簡單的 URL 和 HTTP 方法來操作資源。

> 其核心思想是，每一個 URL 都代表一個資源，而不同的 HTTP 方法（如 GET、POST、PUT、DELETE）用來對這些資源進行不同的操作。
> * `GET` /users：取得用戶的資料。
> * `GET` /users/{id}：取得特定用戶的資料。
> * `POST` /users：新增新的用戶資料。
> * `PUT` /users/{id}：更新特定用戶的資料。
> * `DELETE` /users/{id}：刪除用戶資料。

### 資料來源
* [API串接功能，你不可不知道的網頁技術知識](https://www.lohaslife.cc/post/article-api-knowledge)
* [新手指南：什麼是 RESTful API？](https://realnewbie.com/basic-concent/what-is-restful-api)

## 網址結構
:::info
以 `https://tdx.transportdata.tw/api/basic/v2/Tourism/ScenicSpot/Kaohsiung?%24top=50&%24format=JSON` 為例。
:::
* 到 `?` 號之前的 `https://tdx.transportdata.tw/api/basic/v2/Tourism/ScenicSpot/Kaohsiung` 是網址的主體。
* 使用 `?` 串接參數。
* `top=50`、`format=JSON` 為參數。
* 參數與參數之間使用 `%` 連接。

## 串接 API 的四種種類

| 讀取位置 | 是否需申請帳號 | 資料種類 |
| ---------- | -------------- | ------------------------------------------------------ |
| 瀏覽器端 | ❌ | 政府的 Open data。 |
| 瀏覽器端 | ✔️ | 沒有高度敏感資料的服務，但需要辨識使用者，且會限流（只能讀取 100 次之類的）。 |
| 後端伺服器 | ❌ | Open data 居多，但該服務不想承受請求壓力。 |
| 後端伺服器 | ✔️ | 高度敏感資料，需要辨識使用者，以最安全的方式取得資料。 |

若 Response headers 裡面的屬性 `Access-Control-Allow-Origin` 顯示 `*`，表示「允許任何來源」都可以發起跨域請求並讀取回應。

## 常見的審核與請求方法
### API KEY（金鑰）與 Token（令牌）
* 某些 API 需要經過審核才可以串接，因此 API KEY 與 Token 的設計就是審核。
* API KEY 通常用於識別使用者；而 Token 用於授權使用者權限。

### 常見的請求方法

## 什麼是 Swagger？
> Swagger 是一間名為 SmartBear Software 的公司，開發出的 REST API 的工具，可以幫助設計、構建、記錄和使用 REST API。

> 能建立清晰明瞭的 REST API 規格文件。

### 資料來源
* [使用 Swagger 自動建立清晰明瞭的 REST API 文件](https://ithelp.ithome.com.tw/articles/10242295)

## 為什麼有些 API 會有 ID 資訊？
* 避免資料撞名，例如身份證號碼。
* [通用唯一辨識碼 UUID](https://zh.wikipedia.org/zh-tw/%E9%80%9A%E7%94%A8%E5%94%AF%E4%B8%80%E8%AF%86%E5%88%AB%E7%A0%81)

## API 實作練習
### 文件
* [API 教學文件](https://chalk-freedom-ec6.notion.site/API-8b5b74eb052b451faf28013d76811fac#7598a1040d4f4c4aab5dec30f621d2b8)
* [API 申請平台](https://livejs-api.hexschool.io/)
* [API 線上測試文件](https://hexschool.github.io/hexschoolliveswagger/)
> 在這裡，前端負責將介面與服務串接起來，但實際上「新增」、「修改」與「刪除」等業務邏輯，是由後端負責的。

### 如何在測試文件中執行 API？
1. 申請 API 路徑。
2. 切換到測試文件，點選任一支 API。
3. 點選 Parameters 旁的 Try it out。
4. 在 api_path 欄位輸入剛剛申請的 API 路徑。
5. 點選下方 Execute，即可收到 Responses 的資料。

### 程式碼

// 組合 API 路徑
// 每支 API 的基本路徑相同
// 可將相同的部分宣告成變數管理
const baseUrl = "https://livejs-api.hexschool.io/api/livejs/v1/customer/";
const apiPath = "eeeee750217";
const productsApiUrl = `${baseUrl}${apiPath}/products`;

// 取得產品列表
function getProducts() {
  axios
    .get(productsApiUrl)
    .then(function (res) {
      console.log(res.data.products);
    })
    .catch(function (err) {
      console.log(err.response.data.message);
    });
};