【譯者注】本文是作者在自己的作業經驗中總結出來的RESTful API設計技巧，雖然部分技巧仍有爭議，但總體來說還是有一定的參考價值的，以下是譯文，
簡單說一下代碼重用
記得在Ken Rogers的Medium博客里曾經見過這么一句話（原文出自海明威）：
我們都是手藝學徒，沒有人會成為大師，
在我寫這篇文章的時候，我不禁笑了起來，因為從這件事情的背后看到了一個偉大的類比，那就是從其他人那里參考了海明威的話，也就是說，我不需要為了得到類似的功能和結果而花費精力自己去創建一個與眾不同的東西，上面提到的海明威的話正是代碼重用在文學上的例子，
但是，我在這里不會寫代碼包的好處，而是更多地提一些我的感受，這些感受會在當前以及未來的專案中積極地得到實作，我還總結了一套API規則和原語，包括了功能和實作細節，
使用API版本控制
如果你要開發一個提供客戶端服務的API，你需要為最后可能的修改而做好準備，最好的辦法就是通過為RESTful API提供“版本命名空間”來實作，
我們只需將版本號作為前綴添加到所有的URL里即可，
GET www.myservice.com/api/v1/posts
然而，在我研究了其他的API實作之后發現，我喜歡上了這種較短的URL樣式，它把api作為是子域名的一部分，并從路由中洗掉了/api，這樣更短、更簡潔，
GET api.myservice.com/v1/posts
跨域資源共享（CORS）
需要重點關注的是，如果你打算在www.myservice.com上托管你的前端站點，而將API放在另外一個不同的子域上，例如api.myservice.com，那么你需要在后端實作CORS，這樣才能使得AJAX呼叫不會拋出 No Access-Control-Allow-Origin header is present 這樣的錯誤，
使用復數形式
當你從/posts請求多個帖子的時候，這樣的URL看起來更明了：
// 復數形式看起來更一致，更有意義
GET /v1/posts/:id/attachments/:id/comments
// 不能有歧義
// 這只是一個評論？ 還是一個表格？
GET /v1/post/:id/attachment/:id/comment
更多有關混合型別的資訊，請看下文：“使用根級別的‘me’端點（URL）”，
避免查詢字串
查詢字串的作用是對關系資料庫回傳的記錄集做進一步地過濾，
/projects/:id/collections 優于 /collections?projectId=:id，
/projects/:id/collections/:id/items 優于 /items?projectId=:id&collectionId=:id，
更多資訊請看下文：“避免對嵌套路由的操作”，
使用HTTP方法
我們可使用下面這些HTTP方法：
-
GET 用于獲取資料，
-
POST 用于添加資料，
-
PUT 用于更新資料（整個物件），
-
PATCH 用于更新資料（附帶物件的部分資訊），
-
DELETE 用于洗掉資料，
補充一點，對于修改物件的部分內容的請求來說，我認為PATCH是減少請求包大小的一個好的方法，并且它也能很好的跟自動提交/自動保存欄位配合起來用，
一個很好的例子是Tumblr的“儀表盤設定”螢屏，其中，“服務的用戶體驗”的一些非關鍵性選項可以單獨地編輯和保存，而不需要點最下面的提交按鈕，
對于POST，PUT或PATCH的成功回應訊息，應該回傳更新后的物件，而不是只回傳一個null，點擊這里有一篇http1.0和2.0的對比，
有關回應的其他內容，請閱讀下文：“JSON格式的回應和請求”，
使用封包
“我不喜歡資料封包，它只是引入了另一個鍵來瀏覽資料樹，元資訊應該包含在包頭中，”
最初，我堅持認為封包資料是不必要的，HTTP協議已經提供了足夠的“封包”來傳遞回應訊息，
然而，根據Reddit上的回復所述，如果不封包為JSON陣列，則可能會出現各種漏洞和潛在的黑客攻擊，
現在建議使用封包，你應該把資料封包后再應答！
// 已封包，最頂級的物件既安全又簡潔
{
data: [
{ ... },
{ ... },
// ...
]
}
// 未封包，存在安全風險
[
{ ... },
{ ... },
// ...
]
同樣要重點關注的是，不像其他語言那樣，JavaScript之類的語言將會將空物件認為是true！ 因此，在下面這種情況下，不要回傳空的物件來作為回應的一部分：
// 從payload中提取封包和錯誤
const { data, error } = payload
// 錯誤處理
if (error) { throw ... }
// 否則
const normalizedData = https://www.cnblogs.com/javastack/p/normalize(data, schema)
JSON格式的回應和請求
所有東西都應該被序列化成JSON，如果你期待從服務器上獲取JSON格式的資料，那么請客氣一點，請發送JSON格式的內容給服務器，請兩邊保持一致！
某些情況下，如果動作執行成功（例如DELETE），那我并沒有什么需要回傳的，但是，在某些語言（如Python）中回傳一個空物件可能被認為是false，并且在開發人員除錯程式的時候，這種情況并不容易發現，因此，我喜歡回傳“OK”，盡管這是一個字串，但是在回傳的時候會被包裝成一個簡單的回應物件，
DELETE /v1/posts/:id
// response - HTTP 200
{
"message": "OK"
}
使用HTTP狀態碼和錯誤回應
因為我們使用了HTTP方法，所以我們應當使用HTTP狀態碼，
我喜歡使用這些狀態碼：
對于資料錯誤
400：請求資訊不完整或無法決議，
422：請求資訊完整，但無效，
404：資源不存在，
409：資源沖突，
對于鑒權錯誤
401：訪問令牌沒有提供，或者無效，
403：訪問令牌有效，但沒有權限，
對于標準狀態
200： 所有的都正確，
500： 服務器內部拋出錯誤，
假設要創建一個新帳戶，我們提供了email和password兩個值，我們希望讓客戶端應用程式能夠阻止任何無效的電子郵件或密碼太短的請求，但外部人員可以像我們的客戶端應用程式一樣在需要的時候直接訪問API，
如果email欄位丟失，則回傳400，
如果password欄位太短，則回傳422，
如果email欄位不是有效的電子郵件，則回傳422，
如果email已經被使用，回傳一個409，
從上面這些情況來看，有兩個錯誤會回傳422，不過他們的原因是不同的，這就是為什么我們需要一個錯誤碼，甚至是一個錯誤描述，要區分代碼和描述，我打算將error（代碼）作為機器可識別的常量，將description作為可更改的用于人類識別的字串，點擊這里有一篇http1.0和2.0的對比，
欄位校驗錯誤
對于欄位的錯誤，可以這樣回傳：
POST /v1/register
// 請求
{
"email": "end@@user.comx"
"password": "abc"
}
// 回應 - 422
{
"error": {
"status": 422,
"error": "FIELDS_VALIDATION_ERROR",
"description": "One or more fields raised validation errors."
"fields": {
"email": "Invalid email address.",
"password": "Password too short."
}
}
}
操作校驗錯誤
對于回傳操作校驗錯誤：
POST /v1/register
// 請求
{
"email": "[email protected]",
"password": "password"
}
// 回應 - 409
{
"error": {
"status": 409,
"error": "EMAIL_ALREADY_EXISTS",
"description": "An account already exists with this email."
}
}
這樣，你的程式的錯誤提取邏輯要當心非200的錯誤了，你可以直接從回應中檢查error欄位，然后將其與客戶端中相應的邏輯進行比較，
status這個欄位似乎也很有用，如果你不想檢查回應里的元資料，那你可以在需要的時候有條件地添加這個欄位，
description可作為備用的用戶可讀的錯誤訊息，
密碼規則
在做了很多密碼規則的研究之后，我比較贊同《密碼規則是廢話》（https://blog.codinghorror.com/password-rules-are-bullshit/）和《NIST禁止做的事情》（https://nakedsecurity.sophos.com/2016/08/18/nists-new-password-rules-what-you-need-to-know/）這兩篇帖子的觀點，
整理了一些處理密碼的規則：
1. 執行unicode密碼的最小長度策略（最小8-10位），
2. 檢查常見的密碼（例如“password12345”）
3. 檢查密碼熵（不允許使用“aaaaaaaaaaaaa”），
4. 不要使用密碼撰寫規則（至少包含其中一個字符“！@＃$％＆”），
5. 不要使用密碼提示（“assword”這樣的），
6. 不要使用基于知識的認證，
7. 不要超期不修改密碼，
8. 不要使用短信進行雙認證，
9. 使用32位以上的密碼鹽（salt），
在某種程度上，所有這些規則能使密碼驗證更容易！
使用訪問和重繪令牌
現代的無狀態、RESTful API一般會使用令牌來實作身份認證，這消除了在無狀態服務器上處理會話和Cookie的需要，并且可以很容易地使用Authorization頭（或access_token查詢引數）來除錯網路請求，點擊這里有一篇JWT生成token實戰，
訪問令牌用于認證所有未來的API請求，生命期短，不會被取消，
重繪令牌在初始登錄的回應中回傳，然后跟過期時間戳和與使用者的關系一起進行散列計算后存盤到資料庫中，這個長生命期的像密碼一樣的密鑰，可以被用來請求新的短生命期的JWT訪問令牌，重繪令牌也可以用于續訂并延長其使用壽命，這意味著如果用戶持續使用該服務，則無需再次登錄，
但是，如果API希望簽訂一個不同的“密鑰”，JWT就會被取消，但是這將使所有當前發出的令牌全部無效，但因為這些令牌是短生命期的，所以這并沒有關系，
登錄
在我的程式實作中，正常的登錄程序如下所示：
1. 通過/login接收郵件和密碼，
2. 檢查資料庫的電子郵件和密碼哈希，
3. 創建一個新的重繪令牌和JWT訪問令牌，
4. 回傳以上兩個資料，
續訂令牌
正常的續訂驗證流程如下所示：
1. 嘗試從客戶端創建請求時，JWT已經過期，
2. 將重繪令牌提交到/renew，
3. 通過將重繪令牌進行哈希與資料庫中保存的進行匹配，
4. 成功后，創建新的JWT訪問令牌并延長到期時間，
5. 回傳訪問令牌，
驗證令牌
通過檢查到期日期和簽名哈希可以校驗JWT訪問令牌的有效性，如果校驗失敗，則認為是一個無效的令牌，
如果驗證通過，則JWT的有效載荷中包含了一個uid，它用于在API回應的背景關系中傳遞一個對應的user物件來檢查權限/角色，并相應地創建/讀取/更新/洗掉資料，
終止會話
由于重繪令牌存盤在資料庫中，因此可以將其洗掉來“終止會話”，這為用戶提供了一個控制方法，即他們可以通過主動的重繪令牌“會話”來保護自己的帳戶，并且通過這種方法來進行多次重復認證（通過調整超時時間戳來實作），
讓JWT保持小巧
在把資訊序列化到JWT訪問令牌中時，請盡可能地讓這個資訊小巧，身份驗證令牌的生命期不需要很長，因此沒必要，如果可以的話，只序列化用戶的uid（id）就可以了，其余的可以通過“GET /me”來傳遞，點擊這里有一篇JWT生成token實戰，
還值得注意的是，存盤在JWT有效載荷中的任何敏感資訊并不安全，因為它只是一個經過base64編碼的字串，
使用根級別的“Me”端點（URL）
一般人會使用/profile這個URL來提供自身的基本屬性，但是，我也看到過比較混論的實作，例如對于/users/:id這種接受整數的URL，它竟然允許傳入字串me來指向自身的屬性，
通過/me訪問自身資訊的更深層次的URL，例如/me的/settings或者/billing資訊，而通過users/:id/billing訪問其他用戶的資訊，
// 不推薦
GET /v1/users/me
// 推薦，因為更短，沒有把整數和字串混在一起
GET /v1/me
避免對嵌套路由的操作
有一個采用了以上一些設計理念的重構的專案，最后卻設計出了一個難用的URL系統：
// 一個長長的URL
PATCH /v1/projects/:id/collections/:id/items/:id/attachments
如果要POST上傳一個附件，這個URL可能看起來還行，但是如果在開發客戶端應用程式時想要實作像對附件標星號這么一個簡單操作的功能的話，那你就需要重寫相關的代碼，相關代碼如下：
const apiRoot = 'https://api.myservice.com/v1'
const starAttachment = (projectId, collectionId, itemId, attachmentId, starred) => {
fetch(
`${apiRoot}/projects/${projectId}/collections/${collectionId}/items/${itemId}/attachments/${attachmentId}`,
{
method: 'PATCH',
body: JSON.stringify({ starred }),
// ...
}
}
attachments.js
助手函式的代碼如下：
import { starAttachment } from './actions/attachments.js'
class MyComponent extends React.Component {
doStarAttachment = (id, starred) => {
// now all the "boilerplate" for starring the attachment
const {
projectId,
collectionsId,
itemId
} = this.props.entities.attachments[id]
// now actually plugging in all that information
starAttachment(projectId, collectionId, itemId, id, starred)
}
// ...
}
MyComponent.js
如果你把獲取附件屬性這個功能委派給服務器來實作，并且只使用根級別的URL，這樣不是更好嗎？
const apiRoot = 'https://api.myservice.com/v1'
const starAttachment = (id, starred) => {
fetch(
`${apiRoot}/attachments/${id}`,
{
method: 'PATCH',
body: JSON.stringify({ starred }),
// ...
}
}
attachments.js
import { starAttachment } from './actions/attachments.js'
class MyComponent extends React.Component {
doStarAttachment = (id, starred) => {
// simple as, and you could even easily call it from a gallery-like list
starAttachment(id, starred)
}
// ...
}
MyComponent.js
總的來說，我認為這兩種方法各有各的優勢，而我傾向于用一個長的路徑來創建/提取資源，用一個短的路徑來更新/洗掉資源，
提供分頁功能
分頁很重要，因為你不會想讓一個簡單的請求就獲得數千行的記錄，這個問題似乎很明顯，但是還是會有許多人忽略這個功能，
有多種方法來實作分頁：
“From”引數
可以說這是最容易實作的，API接受一個from查詢字串引數，然后從這個偏移量開始回傳有限數量的結果（通常回傳20個結果），
另外最好提供一個limit引數來限制最大記錄數，例如Twitter，最大限制為1000，而默認限制為200，
“下一頁”令牌
如果每頁20個結果之外還有其他的結果，谷歌的Places API就會在回應中回傳next_page_token，然后，服務器在新的請求中接收到這個令牌后，就會回傳更多的結果，并附帶新的next_page_token，直到所有的結果全部都回傳給客戶端，
Twitter使用引數next_cursor實作了類似的功能，
實作“健康檢查”URL
很有必要提供一種方法來輸出一個簡單的回應，以此來表明API實體是活著的，不需要重新啟動，這個功能也很有用，通過它可以很方便地檢查某個時間點的某臺服務器上的API是什么版本，而這無需通過認證，
GET /v1
// response - HTTP 200
{
"status": "running",
"version": "fdb1d5e"
}
我提供了status和version這兩個值，另外值得一提的是，這個值是從version.txt檔案讀取到的，如果讀取錯誤或者檔案不存在，則默認值為 :__UNKNOWN__，
原文：https://medium.com/@petertboyer/learn-restful-api-design-ideals-c5ec915a430f
作者：Peter Boyer
翻譯：雁驚寒
近期熱文推薦：
1.Java 15 正式發布， 14 個新特性，重繪你的認知！！
2.終于靠開源專案弄到 IntelliJ IDEA 激活碼了，真香！
3.我用 Java 8 寫了一段邏輯，同事直呼看不懂，你試試看，，
4.吊打 Tomcat ，Undertow 性能很炸！！
5.《Java開發手冊（嵩山版）》最新發布，速速下載！
覺得不錯，別忘了隨手點贊+轉發哦！
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/238318.html
標籤：Java
上一篇：【IDEA】修改代碼頭注釋