[PHP][API]Chapter 6: API Design

本章節標誌一個轉折點在我們瞭解 APIs 的過程中。我們已經瞭解了組成部分，現在我們將瞭解如何將概念結合起來，形成一個 API。在這一章節裡，我們將通過設計一個 API 來探討 API 的組成元件。

組織資料

國家地理預計，在2011年，美國人將拍 80 億張照片。隨著這麼大量的照片數量，你能想象每個人都使用不同的辦法整理這些照片。有些人喜歡把所有東西放到一個單一的檔案夾中。有些人會按照年份、月份、事件的檔案夾的階層來分類。

公司在組織上也有相似的想法，當建立它們的他們的 APIs 時。正如我們在第一章提到的，API 的目的是讓電腦與公司的資料跟容易配合。顯而易見，一個公司可以決定使用一個單一的 URL 對於所有資料並且使他們可以方便搜尋（比如像把你所有的照片放到一個檔案夾）。另一種方式，每一種資料有它自己的 URL ，在層級組織中（就像照片有它的檔案夾和子檔案夾）。每家公司選擇最好的方式構建它們的 API 應對不同的形式，在現有的行業經驗引導下。

選擇一種形式開始

當討論 APIs 的時候，你可能會聽到“soap”和“rest”的說法，並且很疑惑這個開發商到底是在工作還是計劃休假。事實是這些是基於網路的 API 的兩個常見體系的名稱。SOAP（acronym 的縮寫）是一種基於 XML 的設計，擁有標準化的結構來請求和響應。REST，代表表述性轉移，是一個比較開源的，提供了大量的協定，但是留下許多需要在設計 API 時候商榷的地方。

通過這個課程，你可能主要到我們更偏愛 REST APIs。這種偏愛是大多數的，因為 REST 採用令人難以置信的速度。這並不是說 SOAP 是邪惡的，它也有它的優勢。儘管如此，我們的討論焦點依然停留在 REST ，因為這是你最可能碰見的 API 。在剩下的部分，我們將瞭解組件通過做一個 REST API。

我們的第一個資源

回想第2章節，我們聊了一點關於資源的事情。回想一下，資源就是 API 的名詞（顧客和披薩）。這些都是我們希望世界通過 API 互動的東西。

為了感受一個公司是如何開始設計 API 的，讓我們嘗試聯絡起我們的披薩店。

對於用戶端，以便能夠與披薩店聯絡起來，我們需要做幾件事：

1. 決定什麼資源是可用的。
2. 分配 URL 到這些資源。
3. 決定用戶端應該對這些資源可以進行什麼樣的動作。
4. 找出每一步需要哪些資料，他們應該是什麼樣的格式。

擷取資源是第一個艱難的任務。一個解決這個問題的方法就是逐步執行典型的相互作用。對於披薩店來說，我們可能又一個菜單。在菜單上是各種披薩。當顧客想要我們我們做其中一種蛋糕，他們需要下訂單。在這方面，菜單，披薩，顧客和訂單聽起來是不錯的資源。讓我們從訂單開始。

下一步就是分配這些 URL 到資源。有很多的肯能性，但幸運的是 REST 約定給予了一定支援。在一個典型的 REST API ，資源將分配兩個 URL 。首先是資源的名稱的複數，如 /orders 。第二個是資源名稱的複數加一個唯一的標識符指定單個資源，如 /orders/ ,其中 是一個命令的唯一識別碼。這兩個 URL 模式構成了我們的 API 將支援第一端點。這些被稱為端點的，僅僅因為他們放在了 URL 的末端，如 http://example.com/ 。

由於我們選擇了資源並分配了 URL ，我們需要決定用戶端可以採取什麼樣的行動執行。根據 REST 的約定，我們可以知道複數端點( /orders ) 用於列出現有的訂單和創造新的訂單。有一個唯一識別碼的端點（ /orders/ ），用來檢索、更新或取消一個特定的順序。用戶端告訴服務端通過 HTTP 通道將傳輸什麼樣的動作（GET、POST、PUT、DELETE）在請求中。

總之，我們的 API 現在看起來是這樣的：

| HTTP verb | Endpoint | Action |

| ——— | ——— | ———————— |

| GET | /orders | List existing orders |

| POST | /orders | Place a new order |

| GET | /orders/1 | Get details for order #1 |

| GET | /orders/2 | Get details for order #2 |

| PUT | /orders/1 | Update order #1 |

| DELETE | /orders/1 | Cancel order #1 |

充實我們的訂單端點的動作，最後一步是決定用戶端和服務端之間需要交換什麼資料。借用我們在第3章節中的披薩店的例子，我們能說一個訂單需要一個麵包皮和夾心的種類。我們還需要選擇用戶端和服務端之間傳遞資訊的資料格式。XML 和 JSON 都是很好的選擇，但對於可讀性，我們選擇 JSON。

在這一點上，你已經設計了一個功能性的 API 。下面是用戶端和服務端使用 API 進行互動的樣子：

把資源串連在一起

我們的披薩店的 API 看起來很尖銳。訂單以前所未有的方式進來。事實上，生意是非常的好，我們決定要開始根據顧客的忠誠度來跟蹤訂單了。一個簡單的新方法做到這一點就是增加一個新的客戶資源。

就像訂單一樣，我們的客戶資源需要一定的端點。如以下約定， /customers 和 /customers/ 很好的鍥合。我們跳過這些細節，但我們假設我們的每個行為為每個端點添加意義，哪些資料代表一個客戶。假設我們做了一切，我們又一個有趣的問題：我們如何讓訂單和使用者發現聯絡？

REST 從業者執著於如何解決資源相關聯的問題。有人說，階層應該繼續增加，增加端點就像 /customers/5/orders 指第五個顧客的訂單， /customers/5/orders/3 指第五個顧客的第三個訂單。其他人則認為應該讓事情變得更簡單一些，通過在一個資料相關的詳細資料。在這種模式下，建立訂單 custonmer_id 可附帶訂單資訊。這兩種在使用 REST APIs 中都比較廣泛，所以都值得瞭解一下。

搜尋資料

隨著一個系統資料的增加，端點列出所有的記錄變得不切實際。試想一下，如果我們的披薩店有 300 萬 完成的訂單，你想瞭解有多少的澆頭為辣香腸。發送一個 GET 請求給 ／orders 並且收到所有 300 萬訂單將變得沒有用。幸運的是，REST 有個極好的方法搜尋資料。

URLs 有一個我們沒有提到過的組件，query sting （查詢字串）。查詢是指搜尋和字串表示的文本。查詢字串是一些文本，去到一個 URL 的末尾，通過 URL 傳遞資訊。例如，在問號之後的資訊都是查詢資料： http://example.com/orders?key=value 。

REST API 使用查詢字串來定義搜尋的細節。這些細節被稱為查詢參數。API 決定它將接收什麼參數，需要使用這些確切名稱實現搜尋。我們的披薩店 API 允許用戶端搜尋訂單通過 URL : http://example.come/orders?topping=pepperoni 。用戶端又可以通過列出一個有一個參數進行查詢，用符號（“&”）隔開，查詢多個參數。例如： http://example.com/orders?topping=pepperoni&crust=thin 。

查詢串的另一個用途時要限制在每個請求中返回的的資料數量。通常，API 將結果分成組（100或500的記錄）中，在一個時間內返回一組。這些分割了的資料的過程被稱為分頁（比喻將單片語成頁）。允許用戶端翻閱所有資料，該 API 將支援查詢參數允許用戶端置頂它想要的資料頁面。在我們的披薩店 API ，我們可以通過支援分頁，允許客戶指定兩個參數：頁面和大小。如果用戶端使的請求像 GET／orders?page=2&size=200 ，我們都知道他們想要結果是第二頁，每頁 200 個結果，訂單 201-400。

第六章小結

在本章節，我們學習了如何設計一個 REST 的 API。我們發現了 API 支援的準系統，以及如何組織資料，以便它可以被電腦容易吸收。

我們所瞭解的關鍵點：

• SOAP : API 架構標準化的資訊格式。
• REST : 控制資源中心的 API 架構。
• Resource :API 項目的一個名詞就像顧客和訂單。
• Endpoint ：構成一部分 API 的 URL。在 REST 中，每個資源都有自己的端點。
• Query String ：用於資料傳遞給伺服器的 URL 的一部分。
• Query Parameters ：在查詢字串中發現的值（topping＝cheese）。
• Pagination ：分離結構到管理模組的過程。

