大類的技術手記

GET

取得資源。

最常見的方法，可以取得所需的資源，成功就會回傳 HTTP 狀態碼 200 OK ，如果資源不存在就會回傳 404 Not Found 。

POST

通常用來建立新資源或是新任務。

請求內容通常會包含建立新資源所需要資訊，接著服務端便會回傳新資源的 URI 和資源的詳細內容。

如果確實建立了新資源，會回傳 HTTP 狀態碼 201 Created ，如果這個要求進行了處理，但未建立新資源，則可選擇回傳狀態碼 200 OK 。

有時建立的新資源沒有可回傳的內容，那麼就可以直接回傳 204 No Content 。

如果用戶端在建立新資源的時候，內容不合法(比如說缺失內容或格式不對等)，可以回傳狀態碼 400 Bad Request ，並在回傳內容包含關於錯誤的資訊。

PUT

會建立資源或更新現有的資源。

請求內容會包含要建立或更新的資源，若具有此 URI 的資源已經存在，則會取代此資源。否則會建立新的資源 (若伺服器支援此動作)，但多數情況主要都是用來更新資源內容。

與 POST 相同，如果建立新資源會回傳 201 OK ，如果更新了現有資源，就會傳回 200 OK 或 204 No Content 。

在某些情況下可能會無法更新資源，這時可以考慮回傳狀態碼 409 Conflict ，並且回傳衝突的原因讓用戶端重送，比較常見的情況是上傳的資源比當前的資源還舊的時候發生。或是內容格式不對，回傳 400 Bad Request 。

PUT 有一個重要的特性即是等冪性。若用戶端多次送出相同的 PUT 要求，結果應該永遠保持不變。

PATCH

要求會針對現有的資源執行「部分更新」。

用戶端會指定資源的 URI。要求本文會指定要套用到資源的「變更」集。 這可能比使用 PUT 更有效率，因為用戶端只會傳送變更，而不是傳送整個資源的內容。

理論上 PATCH 也可以建立新的資源 (比如說透過指定一組「null」資源的更新)，但實際上我不曾見過。

我所知使用的方式有兩種，分別是：

• JSON 修補
• JSON 合併修補

其中後者是相對簡單的方式，簡單來說就是直接傳和資源相同格式的內容，但只包含了想更新的欄位。

{
    "price": 12,
    "color": null, // 有時會用 null 代表要刪除該欄位的內容，但這招不一定適合所有情況
    "size": "small",
    // ... 其餘沒有要更新的欄位就不傳
}

回傳的內容和 PUT 的情況差不多，但要注意 PATCH 並不保證冪等性。

DELETE

很簡單，就是移除指定的資源。

通常刪除就會直接回傳狀態碼 204 No Content 。畢竟都刪除了，自然也不會有內容可以回傳。而如果對應的資源不存在，則會回傳 404 Not Found 代表不存在該資源。

HTTP 狀態碼

剛才提到了很多不同的 HTTP 狀態碼，有的代表成功，有的代表失敗，雖然有很多，但大略可以分類幾類：

盡量就不要讓失敗只有 400 Bad Request 或是 500 Internal Server Error 這兩種回傳，使用多種不同的狀態碼來區分不同的情況可以讓前端更了解發生了什麼事，以便做出不同的應對。

回傳的內容

訂好了 Endpoint 和操作方式，接下來就是決定服務端回傳的內容。

首先自然是要先考慮安全性的問題，有些敏感資料像是密碼，雖然使用者創建的時候會需要，但是回傳的時候就不應該出現。

還有就是可讀性，回傳內容一個很重要的要點是需要根據「使用者的需求」來設計。如果目標使用者單純只是對公司內部的人還好說，畢竟可能會有別的不同因素要考量，但如果是會對外開放的 API 就不要忽略這一點。

畢竟如果用你設計的 API，用戶使用時還得不停的查文件，然後驚呼被騙，體驗就會很差。

所以不要用大家看不懂的語言、不要用奇怪的型態、不要使用自定義的縮寫、不要用自以為是的「常識」來假設用戶，這樣都可以減少用戶必須查文件的需求。

比如說型態和內容要符合使用者的預期，有時最讓人不爽的不是看不懂，而是讓使用者以為自己看得懂，但結果卻不符合預期的情況。明明欄位是「message」，但卻回傳一個數字；或欄位是「status」卻回傳 1。請問誰知道 1 代表什麼意思？是 0 代表成功還是 1 代表成功？

除了內容本身以外，考慮網速，我們還得盡可能的減少請求(Request) 的數量，但又不能一次讓使用者下載太多資料造成延遲，這兩者之間必須要取得平衡。

如果一次回應必要資訊給得不足，使用者就得被迫多打幾次請求來拿取必要資訊，造成使用者體感上的延遲和前端開發的麻煩。

那如果一次給完所有資訊呢？

也不見得是好事。

因為雖然對前端開發者來說，一次拿好資料，之後就不用再拿，開發上會比較簡單。但對真正的使用者而言，一次給太大包的資料可能會增加初次顯示的延遲，造成使用者覺得網站很慢的觀感。

而有可能大部分的資料可能不是使用者第一眼就需要看到的，可以用骨架屏顯示大致的框架和部分的內容，再依次顯示其餘的內容，雖然整體其實並不會比較快，但卻有更好的使用者體驗。

這邊提供兩個小技巧：

首先是同樣的資源不用重覆給多次。

如果評論和作者都相同，不需要給每一則評論都給一次作者資料。

// 每則評論都會有對應的作者，但有可能這些評論都是同一個作者
{
    "comments": [
        {
            "content": "頭香",
            "author": {
                "id": 1,
                "name": "兩大類"
            }
        },
        {
            "content": "一樓有病",
            "author": {
                "id": 2,
                "name": "小雞"
            }
        },
        // ...
    ]
}

// 可以把評論和作者拆開來，變成這樣
{
    "comments": [
        {
            "content": "頭香",
            "author": 1
        },
        {
            "content": "一樓有病",
            "author": 2
        },
        // ...
    ],
    // 拆出來，或是直接拆成兩個資源分別請求
    "author": {
        "1": {
                "id": 1,
                "name": "兩大類"
        },
    "2": {
                "id": 2,
                "name": "小雞"
        }
    }
}

另一個技巧就是讓使用者自行決定內容的詳細程度。有時會發生一種情況，那就是 A 畫面需要精簡的資料，而 B 畫面需要比較詳細的資料，所以 API 為了能同時支援 A、B 兩個畫面，就會直接給 B 畫面所需的所有資訊，但其實對於 A 畫面來說，這些多餘的資訊是不必要的。

但其實這件事我們可以給使用者選擇，比如說 A 畫面只需要評論內容：

// GET /comments
{
    "comments": [
        {
            "content": "頭香"
        },
        {
            "content": "一樓有病"
        },
        // ...
    ]
}

B 畫面除了評論內容還需要作者資訊，可以用 query string 的方式指定：

// GET /comments?embed=author
{
    "comments": [
        {
            "content": "頭香",
            "author": {
                "id": 1,
                "name": "兩大類"
            }
        },
        {
            "content": "一樓有病",
            "author": {
                "id": 2,
                "name": "小雞"
            }
        },
        // ...
    ]
}

這樣 A 畫面就不會拿到不需要的資訊。

至於 API 具體回傳的格式，如果公司內部本來就有規範，那自然就繼續延用。但如果沒有的話，我推薦可以參考通用標準的規範，比如說 JSON:API 。

一方面是溝通方便，如果開發者原本就知道這個規範就可以省去學習的成本，而且這類規範除了一些特別極端的例子，幾乎已經考慮到了所有的情況，通常應該會比少數幾個人，在趕工壓力下一拍腦袋想出來的格式還要全面許多。

這些舉一個 JSON:API 官網的例子：

{
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "firstName": "Dan",
      "lastName": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}

看這個例子，我想通常大部分的人需要思考的反而不是缺了什麼，而是不用什麼，所以是一份非常實用的參考資料。

當然 API 並不只是定好 Endpoint 和功能就行了，還有一些重要的議題必須考慮。

授權 (Authentication)

首先，你怎麼知道使用你 API 的人是目標使用者而不是攻擊者呢？

在設計 API 的時候，這幾乎是不可避免必須要討論的東西。

當然了，不同的使用情境會有不同的需求，像是如果只有提供一些唯讀而且沒有敏感的資料也許就不用管這件事，又或是某些公司內部 API 可能也不需要這麼做。

(但也不好說，畢竟如果不小心讓駭客進了內網，那麼問題就大條了)

但如果授權確實是考量的話，最簡單的方式就是 Basic Authentication ，這是最基本的模式，不需要 cookies、session 甚至也不用自行實作網站登入頁面，瀏覽器會自動跳出對話框讓使用者填帳密。

但缺點是非常不安全，其原理就是將帳密用 base64 編碼後放進 HTTP 的 Header 傳給服務端，服務端再以此來確認身份。

但由於 base64 是可以輕易反編碼的，所以一旦被人攔截到封包，你的帳密就直接被人看光光了。

雖然如果網站使用 HTTPS 可以避免這個問題，至少別人無法輕易攔截封包查看裡面的內容，但兩端仍然藏不住。

身為客戶端的瀏覽器會把帳密存起來，如果有人能碰到這台電腦就有可能拿到。

服務端也是如此，使用者可能也不想讓網站維護者實際拿到自己的密碼，畢竟不少人會用同樣的帳密在不同的網站上。如果心存不良的網站持有者（或是能登上那台機器的員工）可能會藉此登入你其他網站，取得機密資訊。

所以通常我們會使用 hash 的方式在傳上服務端之前便用 hash 加密，服務端也只儲存 hash 後的結果做比對。這樣一來使用者就不需要真正上傳密碼給服務端，而服務端又能驗證使用者。

大概念是這樣，但其實還有很多細節，比如說如果單純用密碼 hash，那麼常見的密碼仍會被別人猜到，所以還需要加上「鹽」才行；而因為可能會被 Replay Attack，可能還得加上時間資訊，才不會被人透過重送同樣的封包破解；甚至 Hash 函數本身如果是用 MD5 也不成，因為 MD5 屬於已經被破解的 Hash 函式，所以必須用其他的代替等等，因為不是本文主題，所以這裡就不多提。

總之，因為要考量的點非常多，做得不好反而不安全，所以通常不會自己做，而是用一些成熟的框架解決。

其他還有第三方登入的方式，像 OAuth 等不同的方法，根據自己的業務需要來決定方案。如果你是不知名的廠商，如果不是用第三方登入，使用者可能會直接放棄使用你的網站；如果你的網站足夠大，這種做法可能反而會有反效果，所以還是得視情況而定。

另外還要注意一點，HTTP 的標準提供了一個方式可以傳遞這類密鑰的加密資訊，也就是放在 Header 的 Authorization 中，盡量不要自作聰明放在其它地方，因為其他地方有不同的用途，可能會不利於安全性。

比如說如果直接把密鑰放進 query string 傳遞，就有可能會被存進 log 或是瀏覽器的瀏覽紀錄中，可能就不是好的選擇。

但事情沒有絕對，經過合理的設計，配合一些 sign 的機制，我也是有見過放在 query string 的。

分頁 (Pagination)

要減少使用者下載的延遲，「分頁」通常是一個非常重要的工具，它考慮的是－－如何用合理的方式將 Data 分成多個 HTTP request，讓回傳時的 Response 大小不會過大。

分頁可以減少使用者下載的時間，而且如果不這麼做，以後端角度來說一次可能會抓太多資料，資料庫會不開心！

一個好的有做分頁的 API 應該要能讓使用者選擇「要一次回傳多一個 items」，比如說 /comments?number=12 ，但是別忘了要設定數量的上限，不然資料庫還是會不開心。

至於怎麼設計分頁的系統，則非常看使用情境，我看過最常見也是最基本的方式，就是直接讓使用者指定頁數的大小和頁碼，然後回傳當前的頁碼、單頁總數、總頁數等資訊。

// GET /comments?pageIndex=1&pageSize=20
{
    "comments": [],
    "pagination": {
        "pageIndex": 1,
        "pageSize": 20,
        "totalSize": 30
    }
}

這個方法雖然回傳的資訊很充足，但要取得所需的資訊其實很花資料庫的運算效能，雖然理論上可以用快取，但一個 API 通常會提供多個條件供使用者修改，資料本身也可能很常變動。不一定有辦法對這些狀態都設快取。

而且這種回傳方法可能會有潛在的問題，如果中間突然新增或刪除一個新的 item，使用者在拿取不同頁的時候可能會重覆或是少出現的情況。

另一種設計方式是使用 Cursor，概念上就是類似資料庫使用 offset 的方式拿資料， 因為不是指定「第幾筆資料」而是要「某個位置之後的資料」，所以效能通常會好很多。但這種方式需要限定業務場景才能使用。

順帶一提，在拿列表的時候如果沒有資料，不建議用 404 Not Found，因為 URL 的指向其實不是錯的，只是沒有資料而已，列表不會不存在，只是空的而已。

錯誤處理

在設計 API 的時候，錯誤處理絕對是非常重要的一環。其中最基本的方式就是直接用 HTTP 的狀態碼來表示。

前面有說到 HTTP 定義了非常多狀態碼可以代表失敗的情況，但畢竟是通用規則，顯然不可能滿足所有的業務需求，所以有些人會自行定義更多狀態碼，反正 400 到 499 還有很多空的狀態碼沒有用到。

但我覺得這個做法很奇怪，因為大部分的錯誤都是業務上定義的錯誤，我們不太可能直接用狀態碼表示。

所以到頭來，我們還是得另外定義一個錯誤碼來表示我們業務上的各種不同錯誤狀態。

{
    "code": "400001",  // 另外定義錯誤碼
    "reason": "小雞飛出大氣層啦！"
}

既然如此，似乎就沒有必要另外延伸定義新的狀態碼。HTTP 的狀態碼應該只用來定位大略的問題，而真正的錯誤則由裡頭的錯誤碼決定才對。

更進一步來說，即使是標準，不常見的狀態碼可能也沒必要使用，直接整合成常見的幾個即可。

畢竟真正的錯誤是用自定義的錯誤碼來判斷，那就沒必要用一些奇怪少見的狀態碼來造成前端開發者的困擾。

至於要怎麼做，我覺得還是看公司，還是前面的老話，反正大部分公司的 API 通常都也只有自己公司內部會使用，只要能符合自身業務需求，怎麼定都沒差，能用就成。

不過說是這樣說，也不要所有回傳的狀態碼都全部是 200，也不要不管客戶端錯或是服務端錯誤就全部回傳 500。

理由是因為前端所使用的函式庫很有可能會針對這2xx、4xx 和 5xx 的狀態碼有不同的處理，如果把應該是 4xx 的狀態碼給成 500 反而可能會造成前端開發人員的困擾。

版本 (Versioning)

事情並不是做完就結束，業務會不停地變動，需求會不斷地來，假如不來，那表示你就沒事可幹，那麼老闆就會把你幹掉，所以你最好祈禱事情永遠做不完……

所以說 API 鐵定是會持續更新的。

(如果你還沒被老闆幹掉的話)

但是對外開放的 API，也不能說改就改，畢竟你也不可能要求客戶做到即時更新，所以這時服務端就必須同時提供新舊多個版本的 API 才行。

至於怎麼做？方法有很多，一個常見的做法就是直接將版號放在 URI 裡，如：

http[s]://api.marco79423.net/v1/hens
http[s]://api.marco79423.net/v2/hens

這個方法的好處是非常好管理，直接改 v1 和 v2 即可，對服務端和客戶端都相當簡單，所以通常是第一個採用的做法。

至於缺點的話，概念上不太 RESTful，「資源」應該比較像是永久連結，理論上不應該可以修改，如果說 Internet 是藉由連結互相連結而產生的，改來改去就會爆炸。

以此例來說，明明「雞(hen)」這個資源就是同一個概念，卻用不同的 URI，會讓人覺得「難道 v1 版的雞(hen) 和 v2 版的雞 (hen) 有什麼本質的不同嗎？

不過我個人覺得這比較像是在挑毛病，並不是什麼大的問題，所以有名的案例有很多，像是 Disqus、Tumblr、Twitter、Youtube 等都是這麼做的。

另外似乎也有人用 host 區分：

http[s]://api-v1.marco79423.net/hens/1
http[s]://api-v2.marco79423.net/hens/2

這個方法理論上很簡單，幾乎有剛才的方法的所有好處，而且分不同 Server 很容易，甚至可以輕易做到 v1 和 v2 用完全不同程式碼實現。

但實務上，管理域名的和實作 API 的時常是不同的部門，遠不如實作者自行控制(不同版本直接改路由)比較容易。

而且這個方法同樣也有前者的缺點，因為不同版本的資源還是用不同的 URI。

如果不想改路由，另一個可能的方案就是把版本資訊放在 body 裡，如：

POST /apis/hens HTTP/1.1
Host: marco79423.net
Content-Type: application/json

{
    "version": "1.0"
}

這個方案好處是路由是一致的，但缺點是不同的 Content-Type 會有不同的回傳方式，如果碰到 JSON 或是 XML 好說，但碰到 CSV 或是 JPG/PNG 這類的格式就麻煩了。

如果是放 query string 的話，也等於是在改路由，那倒不如用第一種方法比較方便。

剩下的選擇就是放 Header 了，比如說：

GET /apis/hens HTTP/1.1
Host: marco79423.net
APIVersion: 1.0

但要注意使用自定義的 Header 可能會有 Cache 問題，所以回傳必須要加上 Vary 才能正確運作，類似這樣：

HTTP/1.1 200 OK
APIVersion: 1.0
Vary: APIVersion

不過這種方式使用者可能會不容易注意到版本的變化，畢竟不會有多少人會檢查回傳回來的 Header。而且自定義 Header 就等於要求使用者必須要看文檔才會知道，畢竟有可能是 API-Version 也有可能是 X-Api-Version ，如果不看文檔，誰會猜得出是哪一種啊？

但你說有沒有著名案例呢？還真的有，那就是很愛搞自定義規則的微軟的 Azure。

（怎麼感覺好像一點都不意外？）

話說回來，既然都可以接受放 Header 了，為什麼不直接用 Content Negotiation 的方式判斷版本呢？畢竟 Accept 本來就是設計用來指定資源的不同格式，所以用來指定版本感覺也很合理？

所以 github 就是這麼做的：

# 格式：application/vnd.github[.version].param[+json]
Accept: application/vnd.github+json
Accept: application/vnd.github.v3+json

這樣的好處是放在 Accept 不會有快取的問題，同時也不會有 URL 不一致的狀況，最重要的是非常 RESTful。

另外 Facebook 還有一種比較特別的做法，叫做「 Feature Flagging」，那就是每個 App 都可以設定自選的版本。

如果 API 有更新，就會主動傳訊息給開發者哪些 APP 使用到的 API 更新了，要求使用者調整。

如果改動不影響開發者，開發者就可以選擇 Enable，如果會影響，就可以先暫停。

⋯⋯但幾個月以後還是會強迫更新。

這個方法的好處是官方可以不用一直支援舊版的 API，只需要維護一份和一小部分新的 API 而已，而對使用者來說，如果改的是與 App 無關的功能也不用擔心出問題。

壞處是當使用者轉換 API 的過程中，可能會有一瞬間不能用的情況發生，因為你不能先放 new code 上去。結果為了解決這個問題，可能要在同時寫支援兩個版本才行。

更大的壞處是如果你不是在 facebook 這種超強的大公司，大概很難強迫開發者這麼做。

雖然前面說了這麼多方法，但也許最好的方法是直接詢問你的目標使用者他們想要的是什麼？畢竟每間公司的業務場景可能都不太一樣，不管什麼方法，如果目標使用者覺得不好用就沒意義了。