資料傳遞標準II：同頻率的溝通很重要！

2024 iThome 鐵人賽

DAY 25

佛心分享-IT 人自學之術

30天轉職馬拉松：從0到Offer的學習計畫系列第 25 篇

16th鐵人賽

diverwil1995

2024-10-09 17:17:28

137 瀏覽

分享至

在上一篇文章中，我們介紹了 JSON 的基礎知識。今天，我們將探討 HTTP request methods、API 和 RESTful API，並且看看如何將這些概念與 JSON 結合應用在實際案例中，Go!

HTTP request methods

HTTP（超文字傳輸協定）是網際網路通訊的基礎協定，作為軟體開發者，我們也必須理解其中的基礎操作概念，以下簡述最常見的方法：

GET：取得資源
POST：建立新資源
PUT：更新現有資源
DELETE：刪除資源
PATCH：部分更新資源

API

API（Application Programming Interface）所謂的應用程式介面，是用於不同軟體元件之間的溝通，可想像為標準化資料交換介面，預先定義好傳遞、回傳內容格式以達到有效率的溝通。它就像是顧客跟服務生之間的溝通，顧客藉由菜單（預先定義好的內容格式）向服務生進行點餐，上面寫著牛肉炒飯一份 $100，所以我付了 $100 就會取得一份熱騰騰的牛肉炒飯。

API 有什麼好處？

提高開發效率：透過 API，開發者能輕鬆串連不同軟體的功能，無需了解其內部實現細節，就能快速整合各種服務。例如：整合 Facebook Login API，省去自己開發複雜的身分驗證系統。
降低溝通成本：API 提供了標準化介面，讓不同系統能夠使用相同的「語言」進行溝通，大幅減少了溝通時的誤解和錯誤。例如：只需遵循 Facebook API 使用規範，即可快速整合所需功能。
促進創新發展：API 使得開發者能夠基於現有服務創造新的應用，激發創意並擴展原有服務的價值。例如：Uber 透過 Google Map API 顯示附近車輛位置、規劃路線、預估抵達時間。
可靠的安全性：API 可以作為一個「守門員」，控制外部對內部系統的存取，有效管理資料的存取權限。例如：Instagram Private Account 會限制請求，只有允許追蹤的使用者能看見。

上述說明了 API 如何在現實世界中發揮重要作用，不僅提高了開發效率，不同的服務和應用能夠相互連接，創造出更大的價值，同時還確保了使用者資料安全和隱私。

RESTful API

是一種主流設計風格，用於創建可擴展且容易使用的標準，它遵循以下幾個主要原則：

資源導向：使用名詞而非動詞來表示資源
迎合 HTTP request methods：使用 HTTP 請求方法來執行操作
無狀態：每個請求都包含完整的資訊，不依賴伺服器端儲存的工作階段狀態
統一介面：使用一致的 URL 結構和回應格式

讓我們以一個簡單的部落格系統為例，看看 RESTful API 如何設計：

獲取所有文章列表
```
GET /api/posts
```
獲取特定 ID 的文章
```
GET /api/posts/{id}
```

創建新文章

POST /api/posts

請求內容（JSON）：

{
  "title": "我的第一篇文章",
  "content": "這是文章內容...",
  "author": "Wilson"
}

更新特定 ID 的文章

PUT /api/posts/{id}

請求內容（JSON）：

{
  "title": "更新後的標題",
  "content": "更新後的內容...",
  "author": "Wilson"
}

刪除特定 ID 的文章
```
DELETE /api/posts/{id}
```

這個簡單的部落格 API 展示了 RESTful 設計的幾個關鍵原則：

使用名詞（posts）來表示資源
使用不同的 HTTP method（GET、POST、PUT、DELETE）來執行不同的操作
URL 結構一致，利用 ID 來分別不同資源
可以想像每個請求都包含了完整的資訊，不依賴於之前的請求狀態

透過這個簡單的例子，我們可以看到 RESTful API 如何以一種直觀和一致的方式設計 API 端點。

當我們用 Uber 叫車時，背後傳遞了些什麼資訊？

我們透過實際案例來解析 API 如何運作，由於過程涉及多個細節，為了簡化，讓我們專注在幾個重要步驟：

步驟 1：尋找可用車輛

當你打開 Uber 並輸入目的地時，Uber 會向伺服器發送一個 GET 請求，以獲取附近可用的車輛。

API 調用：

GET /api/v1/vehicles?latitude=25.0330&longitude=121.5654&radius=3000

伺服器回應的 JSON 可能如下：

{
  "vehicles": [
    {
      "id": "abc123",
      "type": "UberX",
      "latitude": 25.0340,
      "longitude": 121.5650,
      "eta_minutes": 3
    },
    {
      "id": "def456",
      "type": "UberXL",
      "latitude": 25.0320,
      "longitude": 121.5660,
      "eta_minutes": 5
    }
  ]
}

步驟 2：送出叫車請求

當你確認叫車時，Uber 會向伺服器發送一個 POST 請求。

API 調用：

POST /api/v1/ride_requests

請求的 JSON 內容可能如下：

{
  "user_id": "user789",
  "pickup": {
    "latitude": 25.0330,
    "longitude": 121.5654,
    "address": "市政府捷運站"
  },
  "destination": {
    "latitude": 25.0478,
    "longitude": 121.5170,
    "address": "松山車站"
  },
  "vehicle_type": "UberX"
}

伺服器回應的 JSON 可能如下：

{
  "ride_id": "ride123",
  "status": "searching_driver",
  "estimated_price": {
    "amount": 180,
    "currency": "TWD"
  },
  "estimated_duration_minutes": 15
}

步驟 3：接收司機資訊

一旦找到司機，伺服器會主動推送司機資訊到你的應用程式。這通常透過 WebSocket 或長輪詢實現，但為了介紹概念，我們假設它是一個新的 GET 請求。

API 調用：

GET /api/v1/ride_updates/ride123

伺服器回應的 JSON 可能如下：

{
  "ride_id": "ride123",
  "status": "driver_assigned",
  "driver": {
    "name": "王小明",
    "phone": "+886912345678",
    "rating": 4.8,
    "vehicle": {
      "model": "Toyota Prius",
      "color": "白色",
      "plate_number": "ABC-1234"
    }
  },
  "eta_minutes": 3
}