[第六週] API 基礎-實際串接 API、資料格式: JSON、API Method 風格: RESTful

學習目標：能說出 API、RESTful 是什麼、了解 JSON 資料格式、使用 node.js library quest 實際發出 require 串接簡單的 API

關於學習筆記，主要源自於以下學習資源：

• [NET101] 網路基礎概論（搭配 JS 實作練習）
• 網路基礎概論 ─ 重點整理
• Linux Curl Command 指令與基本操作入門教學
• [第四週] API 基礎 — RESTful API、JSON、curl 指令

API 是什麼

• 全名 Application Programming Interface ，中文為應用程式介面
• 是用來交換資訊的管道
• 可以透過 Huli 從拉麵店的販賣機理解什麼是 API （詳細）或下方影片快速了解

影片來源：Termsoup

影片中有提到 API 是所有應用程式、資料及裝置之間的互動資料的交換，但其實不一定要透過網路才有 API 比如說…

• 作業系統裡的 API：讀取、傳輸及寫入等等電腦上的操作。
• 軟硬體廠商的 API：USB 與 電腦交換資料。

而對於網頁來說就是 Web API

• Web API：是一種基於 Http 協定下運算的 API，一切透過網路進行交換資料的操作都是 Web API。

我們後續主要都是介紹 Web API。

我們會利用 WEB API 進行什麼事情呢？

以 API 來說又可以分成「使用」 及 「提供」兩方，以下用圖書館的例子進行說明：

Photo by Monjur Hasan on Unsplash

你是一位圖書館管理員，工程師提供了圖書館資料庫的 API 告知說：「你可以使用這個 API 來進行書籍的管理，這個 API 有四個功能分別是新增、讀取、更新及刪除，你再研究看看吧。」

你一臉茫然地看著丟過來的資訊，開始思考我該怎麼使用 API ….

1. 新增書籍：圖書館進新的書籍，需要把書籍 新增（Create）到資料庫中。
2. 讀取書籍資料：圖書館要在官網上推「被討厭的勇氣」一書，因此要去資料庫讀取（Read）此書的相關資料。
3. 更新書籍資料：糟糕！我們發現「被討厭的勇氣」作者的名字不小心打錯了，要趕快更新（Update）資料庫。
4. 刪除書籍資料：「為愛徬徨的勇氣」一書太熱門了，常常被偷走現在館內一本都不剩了，不打算再進貨此書，要從資料庫刪除（Delete）此書的資料。

以上四種行為就是 API 常見的 CRUD 功能。

CRUD 功能

分別指的是：Create 新增、Read 讀取、Update 更新、Delete 刪除，有時候會聽到五項功能，多了一個 List 列表。

Web API 實際運用場景

• 會員註冊登入：社群連結註冊登入
• 社群嵌入：分享、按讚按鈕、嵌入貼文、留言板、影音，例如：Facebook Graphic
• 資料嵌入，例如：Yahoo 氣象、Google 地圖
• PokeAPI：拿到怪物的資訊
• 假圖 API：隨機 radom 出圖片

實際串接 API

前置作業 — — —

1. Client 端（發出端）。
2. 提供 API 的網站（接收端）。
3. 讓我們發出 request 的地方（工具）。

必須達成以上三要素才能串接，因此我們可以使用…

1. Client 端（發出端）：使用 node.js library request 實作一個 client 端。
2. 提供 API 的網站（接收端）：Regres 是一個提供 API 測試的網站。
3. 讓我們發出 request 的地方（工具）：就是我們的 Terminal 啦。

操作開始 — — —

Step1. 實作一個 client 端

因為在 [第六週] 網路基礎- HTTP、Request、Response 有實作過，這邊就快速說明：

• 新增專案資料夾
• 執行 $ npm install request
• 新增 client.js 並貼上官網提供的範本

Step2. 串接 Regres API

將範例中 google 的網址改成 https://reqres.in/api/users

Step3. 用 node.js 執行

在終端機輸入 $ node client.js

我們將重點放在 body 的部分，body 就是 Regres API 所提供的所有資訊！

資訊好亂好難看！

這是因為 response 的資料是 「JSON 格式字串」不好閱讀也無法使用，因此使用內建函式 JSON.parse() 做處理，就會轉成「JS 物件格式」。

const request = require('request');
request('http://www.google.com', function (error, response, body) {
   console.log('原始格式，JSON 格式的字串 — — — — — ');
   console.log(body);
   console.log('轉成 JS 物件 — — — — — — — — — — ');
   console.log(JSON.parse(body));
});

JS 物件格式 比較好閱讀。＃關於資料格式可參考文章最後

這樣就完成了 API 串接了？不是吧？這樣只是丟一個 request 到那個網站啊？

其實這已經完成了 API 的串接，但得到資訊還不夠，我們應該要可以操作這些資訊，就跟圖書館管理員一樣。但在實作之前我們先來談談 API Method

API Method

之前在 TCP/IP 四層模型 說過，傳遞資續時在應用層必須遵照 HTTP 協定，在這協定之中有個「 Http Request Method」的規定，

使用動詞標準化讓 Server 能清楚辨別 Request 的目的。

而網頁最常見的「Http Request Method」為 Get 及 Post，因此 API 的 Method 就沿用了此項規則，並將真正的指令動詞是寫在 URL

以圖書館資料庫 API 舉例：

真正的指令動詞是寫在 URL

但後來發現這樣問題有點大，URL 命名方式不統一，代表不同的 API 就要去看它的 URL 是怎麼命名的，非常不方便，後來就有一個博士提出了 RESTful 這套「風格」。

RESTful

全名 Representational State Transfer 中文為「表現層狀態轉換」，由 Roy Fielding 博士在 2000 年的博士論文中所提出。他同時也是 HTTP 規範的主要作者之一。是一種軟體架構風格（並非標準），就是一種語意化、更為嚴謹的描述 API 方式，目前也是最常見的方式。

參考資料：Cindy Liu — 什麼是 REST? RESTful?

我們來看看 RESTful 風格的 API 會長什麼樣子

黃底為修改的部分

可以看到 RESTful 的寫法較為一致、也更好理解。

實作 API Method

一樣以 Regres API 進行實作

讀取單一使用者資料

• Method：GET
• url ：https://reqres.in/api/users/<userID>

得到 id 2 的使用者資料

— — — 情境1. 我想要可以帶入 id 作為參數查詢使用者資料？

利用 process.argv 達成帶入參數，先用 console.log 來查看 process.argv 是什麼

const process = require("process");
console.log(process.argv);

是一個陣列，假設在後方輸入數值，會增加到此陣列。＃此圖帶入兩個參數

因此我們就可以利用 process.argv[2] 作為參數帶入！

得到 id 4的使用者資料

新增使用者資料

• method：POST
• url ：https://reqres.in/api/users/
• 另外要到 request library 的 Github 頁面，點選 forms，並將相關資料填入，新增資料至 reqres 。＃這邊只是測試用，並不會真的新增資料。

新增使用者資料

刪除使用者資料

• method：DELETE
• url ：https://reqres.in/api/users/<userID>
• 我們要結合上兩個實作進行

刪除 id 2 的使用者資料

修改使用者資料

• method ：PATCH
• url ：https://reqres.in/api/users/<userID>

修改 id 4 的使用者資料

curl 指令

聽說是很厲害的東西！可以不透過任何工具直接用 Terminal 發出 request 。原本是希望可以結合實作學習，但做完了 week4 回家作業及 week5 挑戰題，好像都沒有用到，看了教學基本上就是寫範例，因此打算先跳過，在此先放上相關的教學連結，相信以後還是要回過頭補上的。

[curl] 基本操作與指令 — 搭配 Lidemy HTTP Challenge 實作（20200724 更）

資料格式 XML & JSON

XML

• Extensible Markup Language，中文：可延伸標示語言。
• 以前傳資料的格式，現代開發比較少用。
• 類似 HTML 內容用前後標籤包起來，缺點：檔案較大不好閱讀。

JSON

• JavaScript Object Notation，中文：JavaScript 物件表示法。
• 基於 JavaScript 的物件產生出來的資料格式。
• 為現代最普遍、常用的資料格式。
• 廣泛應用在各程式語言，前後端分離的興起，需要用 JavaScript 處理後端傳來的資料，而最常使用的交換技術「AJAX」就是使用 JSON 作為交換資料的格式。
• 需注意地方
  1. 乍看之下跟 JavaScript 的物件很像，但它的型態是「字串」。
  2. 但 key 值必需要用雙引號 "key" 包起來。
  3. JSON 格式字串可包含陣列及物件但沒有辦法放 function。
  4. 整個 JSON 格式字串不能使用註解。
• 相關函式
  1. JSON.prase()：將 JSON 格式字串轉成物件。
  2. JSON.stringify()：將物件轉成 JSON 格式字串。
• 其他補充
  1. 好用網站：JSON Editor online，可以將得到的資料轉成 JSON 格式。

重點整理：

• API 是一個傳遞資訊的管道，可比喻成日本拉麵店的販賣機（API），只能操作機器給予的動作，確保廚房（Server）能傳回相對應的餐點（Data）。
• RESTful 是目前主流軟體架構風格，大部分的 API 都是造著此風格實作。
• API 的 CRUD 功能所代表的是：

1. Create 新增
2. Read 讀取
3. Update 更新
4. Delete 刪除。

• 現代普遍的是用 JSON 作為資料的格式。

以上有任何錯誤的地方歡迎指正，感謝。