API設計：先思考再編碼

一個JSON值一千字
讓我們看一個API響應的例子：

{
"data": [
{
"story": "Jonatas Baldin was writing a blog post.",
"created_time": "2017-15-01T00:02:57+0000",
"id": "624510964324764_1046909755418214"
},
]
}

這段JSON的資料是智慧手機從Facebook API響應中收集的Facebook狀態訊息的示例。很漂亮，對不對？

現在想象你是Facebook的工程師，負責這個API。有天您突然決定將id欄位名稱更改為message_id。嗯，這個小的變化可能破壞Facebook。真的。依賴於先前定義的結構的所有裝置現在都無法收集這個JSON響應，也就無法向使用者顯示任何內容。

好壞醜
一個壞的API設計遲早會造成各種麻煩：

1.沒有一致性：一旦API增長，端點往往只是為了滿足即時需求被建立。
2.難以擴充套件：在對端點進行故障排除時無法參考。
3.難學：消費使用資料和開發API會是一段陡峭的學習曲線。
4.效能問題：丟擲未進行規劃設計的API程式碼通常會長期產生效能瓶頸。
5.API往往是永恆的：第一次是讓它就能正確的最好機會。

API是您的應用程式與其使用者之間的合同。它不能突然改變，否則會導致那些已經呼叫它的客戶端發生混亂，API不應該在沒有預見性的情況下倉促建立。這就是需要設計的地方：建立一個規劃或約定，用於構建物件，系統或可衡量的人類互動。

第一件事：讓我們談談HTTP

在介紹API程式碼之前，讓我們先看一下超文字傳輸​​協議HTTP，顧名思義，它是用於在網路上傳輸資料。它有一組關於客戶端和伺服器如何交換資訊的規則。其主要組成部分有：

URL：您的資源在Web上的位置，您的端點的地址。一個示例是使用http://example.org/users列出您的使用者。

請求方法：客戶端希望在特定端點上執行的操作。GET 用於檢索資源，POST建立一個，PUT 和PATCH 來更新現有的資源，DELETE刪除東西。

頭部Header：包含有關客戶端或伺服器的資訊。例如：內容型別（格式）、方法、認證令牌和其他。

正文內容body：客戶端與伺服器之間傳送和接收的資料。JSON是事實上的標準。

狀態程式碼：一個三位數字，用於告知請求狀態。總而言之，2xx 狀態表示成功，4xx意味著客戶端錯誤，5xx意味著服務錯誤。


讓我們看一個HTTP請求/響應示例：

Client request:
GET /users/1 HTTP/1.1
Host: www.example.org/users

Server response:
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Feb 2017 00:43:51 GMT

{
  "id": 1,
  "first_name": "Jonatas",
  "fast_name": "Baldin",
  "role": "Caker"
}
<p class="indent">

良好的API設計需要良好的規格

在設計API時，有一些規範可以幫助您。最常用的是使用純JSON的Swagger、使用YAML表示法的RAML和支援markdown語法的API藍圖Blueprint。我喜歡上了後者：即使它是鄰居新的酷孩子，它已經成熟足夠和能夠讓人愉快的工作。這裡會闡述為什麼。

從官方網站上獲得定義：

API藍圖(支援markdown語法)是簡單的，並且可以在API生命週期的訪問每個元素。它的語法簡潔而富有表現力。使用API​​ 藍圖，您可以快速設計和建立API，或記錄和測試已部署的任務關鍵型API。

它是一個開放原始碼，專注於協作，易於學習和良好記錄的規範，由Apiary建立，其核心是設計第一，周圍有一些很棒的工具：從模擬伺服器生成器到全功能生命週期解決方案。

除了藍圖，還有MSON（Markdown語法物件符號），它以人類可讀的方式定義資料結構，不是手動編寫端點的主體資料，而是在可重用物件中表示它們。

以下是您需要了解的資訊：

API名稱，描述和後設資料：關於API和藍圖版本的一些描述。
資源組：相關資源組，比如Users。
資源：定義唯一資源，它的端點和操作。
引數：在端點中用於指定動態引數，如ID或查詢搜尋。
響應：內容型別，HTTP狀態程式碼和主體資料。

除此之外，蜜蜂是一個協作平臺，用於建立、呈現、測試和服務您的API。他們有一個免費的公共專案計劃，你可以直接用你的GitHub帳戶註冊，以建立自己的設計。

這裡是一個藍圖程式碼示例：

FORMAT: 1A
HOST: http://cakes.ckl.io/

# Cakes API
Cakes is an API used to store and consume information about the most loved Cakes here at Cheesecake Labs.
Cakes是一個API，用於儲存和消費關於Cheesecake Labs最受歡迎的蛋糕的資訊。

# Group Cakes

## Cakes [/cakes/]

### List all Cakes [GET]

+ Response 200 (application/json)

+ Attributes (array[Cake])

# Data Structures

## Cake (object)
+ id: `1` (string, required) - The unique ID of a Cake.
+ name: `Cheesecake` (string, required) - The name of a Cake.
+ rating: `5/5` (string, optional) - The rating of a Cake.
<p class="indent">

該做什麼和不該做什麼

這裡是簡單設計規則和最佳實踐：

1.將端點操作視為CRUD（L）操作
我們的/cakes/端點可能有建立，讀取，更新，刪除和列表操作。你可以使用HTTP動詞和URL來構造這些動作，例如：
列表：GET /cakes/
建立：POST /cakes/
閱讀：GET /cakes/1/
更新：PATCH /cakes/1/
刪除：DELETE /cakes/1/

2.正確使用HTTP方法
GET是獲得，POST是釋出。如果你只是想要一個蛋糕的列表不要使用POST。

3.HTTP是有方法的，使用它們！
POST /cakes/createCake
你不需要在URL中指定操作，我們已經知道POST建立一些東西，所以createCake不需要包含create字眼。

POST /cakes/
更清晰的URL，也會告訴我們可能其他方法將按這種方式使用，如GET /cakes。

4.單數還是複數！

GET /cakes應該返回一個蛋糕列表，所以GET /cake/1應該返回第一個蛋糕，對吧？很不幸的是，不行。即使它在我們的語言是有道理的，它只會用更多端點搞亂客戶端和開發人員。

5.搜尋，排序，限制？使用查詢引數！
此功能允許您指定一些過濾列表端點，這裡是一個例子：
GET /cakes/?name=apple
如果實現，應該所有名稱是蘋果的蛋糕。

GET /cakes/?name=apple&rating=4
您也可以使用連線引數＆，搜尋apple和評級為4的蛋糕。

6.使用4xx返回錯誤。
每個人都憎恨HTTP響應狀態程式碼是2xx，卻返回一個錯誤的訊息！使用正確的程式碼：
401：未經授權的訪問，授權過程未正確完成。
403：禁止訪問，客戶端被授權，但是沒有訪問資源。
404：著名未找到，表示資源不可用。

7.請清楚地描述您的錯誤
當發生問題失敗時，通知客戶端發生了什麼以及如何恢復。這裡有一個很好的方法：

{
  "error": {
    "type": "Authentication Error",
    "details": "Authentication could not be established with the given username and password",
   }
}
<p class="indent">

API Design: Think First, Code Later | Cheesecake L