優(yōu)秀的API設(shè)計(jì)話題，在很多團(tuán)隊(duì)涌現(xiàn)，這些團(tuán)隊(duì)正在努力完善他們的API策略。

在之前發(fā)布的博客上，我簡(jiǎn)要的討論了API設(shè)計(jì)的重要性。一個(gè)設(shè)計(jì)良好的API應(yīng)該包含那些好處：你的API應(yīng)該能提高開發(fā)者經(jīng)驗(yàn)、方便的快捷文檔和高可用性。

但優(yōu)秀的API設(shè)計(jì)究竟應(yīng)該怎么做?在這個(gè)博客中，我將詳細(xì)的介紹一些RESTful API的***設(shè)計(jì)。

一個(gè)設(shè)計(jì)良好的API的特點(diǎn)

一般來(lái)說(shuō)，一個(gè)有效的API設(shè)計(jì)遇有以下特點(diǎn)：

• 易于閱讀和使用。一個(gè)設(shè)計(jì)良好的API應(yīng)該很容易被使用，其資源和相關(guān)操作能夠快速的被使用它的開發(fā)人員記憶。
• 難以誤用。設(shè)計(jì)良好的API實(shí)現(xiàn)和集成將是個(gè)簡(jiǎn)單的過(guò)程，寫出錯(cuò)誤代碼將變得不太可能。沒(méi)有嚴(yán)格按照API開發(fā)指南的終端用戶將會(huì)得到詳實(shí)的信息反饋。
• 完整又簡(jiǎn)潔. ***，一個(gè)完整的API應(yīng)該具有成熟的應(yīng)用防止你的數(shù)據(jù)被泄露。API完整性會(huì)隨著時(shí)間的推移而改變，大多數(shù)的API設(shè)計(jì)人員和開發(fā)人員都應(yīng)在現(xiàn)有基礎(chǔ)上逐步構(gòu)建新的API。這是每一個(gè)使用API的工程師或公司都必須堅(jiān)持的理念。

為說(shuō)明下面列出的概念， 我會(huì)以一個(gè)照片分享的應(yīng)用程序舉例。 該應(yīng)用程序允許用戶上傳照片， 以拍攝地點(diǎn)和心情標(biāo)簽描述照片特征。

集合，資源及其網(wǎng)址

了解資源和集合

資源是REST概念的基礎(chǔ)。 一條資源是一個(gè)重要對(duì)象，它本身可以被引用。 一條資源含有數(shù)據(jù)，與其他資源的關(guān)系，以及操作方法，以允許訪問(wèn)和處理相關(guān)信息。

一組資源被稱為一個(gè)集合。 集合和資源的內(nèi)容取決于你的組織和消費(fèi)者的需求。 例如，如果你認(rèn)為，市場(chǎng)獲得了你的產(chǎn)品用戶群的基本信息會(huì)受益， 那么，你就可以將此作為集合或資源。

統(tǒng)一資源定位器(URL)確定了資源的在線位置。 URL指向你API資源存在的位置。 基URL是這個(gè)位置的一致部分。

在照片分享應(yīng)用一例中， 我們可以公開用戶數(shù)據(jù)，只要用戶通過(guò)集合和資源使用該應(yīng)用程序， 經(jīng)由適當(dāng)?shù)腢RL訪問(wèn)。

1. /users：用戶的集合。
2. /users/username1：一個(gè)特定用戶的信息資源。

名詞化的URL更好

URL應(yīng)該是整潔、優(yōu)雅和簡(jiǎn)單的，這樣開發(fā)人員更易在他們的web程序中使用你的產(chǎn)品。 很長(zhǎng)且難以理解的URL不僅看起來(lái)很糟糕，而且在記錄時(shí)容易出現(xiàn)錯(cuò)誤。所以使用名詞應(yīng)該是很好的。

沒(méi)有規(guī)定讓資源名詞使用單數(shù)或復(fù)數(shù)，但是在如果是集合的話使用復(fù)數(shù)無(wú)疑很好的。 具有相似的資源和集合分別保持它們的一致性是較好的做法。

保持這些名詞的自解釋性，有助于開發(fā)人員了解從URL描述的資源, 這最終會(huì)使他們使用你的API。

回到照片分享應(yīng)用程序，它擁有返回集合的公共API /users 、/photos。注意到它們都是復(fù)數(shù)名詞了嗎? 它們也是自描述的，我們可以推斷出 /users 和/photos分別是獲取產(chǎn)品注冊(cè)的用戶信息和分享的照片。

用HTTP方法來(lái)描述資源的功能

所有資源都有一組方法，可以對(duì)它們進(jìn)行操作由該接口暴露的數(shù)據(jù)。

REStful APIs包含主要的HTTP方法，其良好的定義和獨(dú)立的功能能夠應(yīng)對(duì)所有資源。這里是RESTful API里常用HTTP方法列表，這些方法定義CRUD如何操作資源和集合。

(如果你想了解PUT和PATCH的不同，可以到StackOverflow上看看這個(gè))

雖然在URL中使用動(dòng)詞也不錯(cuò)，但是GET, PUT, POST, DELETE操作已經(jīng)用于描述了資源的操作，因此在URL中使用動(dòng)詞代替名詞會(huì)顯得比較混亂。

在照片分享app中，/users 和/photos 是一個(gè)端點(diǎn)，API的終端消費(fèi)者可以更直觀的使用RESTful CRUD 進(jìn)行上述的操作。

響應(yīng)

提供反饋,以幫助開發(fā)人員成功

在他們使用你的產(chǎn)品時(shí)向開發(fā)人員提供良好的反饋，對(duì)于提升使用率和用戶維持率是很好的。每一個(gè)客戶端的請(qǐng)求和服務(wù)端的響應(yīng)都可以看做是一個(gè)消息，在理想化的RESTful 生態(tài)系統(tǒng)中，這些消息必須是自描述的。

良好的反饋對(duì)于實(shí)現(xiàn)的驗(yàn)證是積極的，錯(cuò)誤實(shí)現(xiàn)產(chǎn)生的消息可以幫助用戶調(diào)試和糾正使用產(chǎn)品的不正確方式。對(duì)于API, 錯(cuò)誤信息是使用API上下文的良好方式之一。

調(diào)整你的錯(cuò)誤與標(biāo)準(zhǔn)HTTP代碼一致。客戶端引發(fā)的錯(cuò)誤應(yīng)該使用400類型錯(cuò)誤，如果是服務(wù)端的錯(cuò)誤應(yīng)該使用500類型來(lái)響應(yīng)。 一個(gè)對(duì)資源操作成功后應(yīng)該返回一個(gè)200類型的響應(yīng)。

有很多的響應(yīng)代碼。想了解更多, 看看這個(gè)REST API教程.

一般來(lái)說(shuō)，使用你的API時(shí)有三種可能就結(jié)果：

客戶端應(yīng)用程序的行為是錯(cuò)誤的(客戶端錯(cuò)誤–4xx響應(yīng)代碼)

API行為錯(cuò)誤 (服務(wù)器錯(cuò)誤- 5 xx響應(yīng)代碼)

客戶端和API工作正常 (成功– 2xx響應(yīng)代碼)

成功解決客戶使用你的API時(shí)遇到的問(wèn)題將大大改善開發(fā)人員使用體驗(yàn)和防止濫用API。 詳細(xì)描述這些錯(cuò)誤，同時(shí)保持簡(jiǎn)明和整潔。在錯(cuò)誤消息中提供足夠的信息有助于用戶解決它們的問(wèn)題，如果你覺(jué)得需要更加詳細(xì)的信息，***另寫文檔并在此處提供鏈接。

GET 響應(yīng)例子

一個(gè)良好設(shè)計(jì)的API應(yīng)該有響應(yīng)示例，以明白是否成功調(diào)用了一個(gè)URL。響應(yīng)示例應(yīng)該簡(jiǎn)單、簡(jiǎn)潔和易于理解的。 一個(gè)好的經(jīng)驗(yàn)法則是：幫助開發(fā)人員在5秒內(nèi)理解一個(gè)成功的響應(yīng)。回到我們的照片分享應(yīng)用，我們定義了 /users 和 /photos URL。 /users 應(yīng)該易數(shù)組的形式提供所有注冊(cè)的用戶，并且包含用戶名稱和加入日期屬性。

你可以在Swagger(OpenAPI)中使用 API設(shè)計(jì)工具來(lái)定義你的API，詳述如下：

responses: 
        200: 
          description: Successfully returned information about users  
          schema: 
            type: array 
            items: 
              type: object 
              properties: 
                username: 
                  type: "string" 
                  example: "kesh92" 
                created_time: 
                  type: "dateTime" 
                  example: "2010-01-12T05:23:19+0000" 

注意數(shù)據(jù)類型和實(shí)例的每個(gè)響應(yīng)項(xiàng)注釋，最終用戶期望的是一個(gè)成功的GET調(diào)用。成功響應(yīng)后最終用戶將接收的JSON看起來(lái)如下：

{ 
   “data”:[ 
      { 
         “Username”:“example_user1”, 
         “created_time":“2013-12-23T05:51:14+0000         ” 
      }, 
      { 
         “username”:“example_user2”, 
         “created_time":“2015-3-19T17:51:15+0000         ” 
      } 
…. 
   ] 
} 

如果用戶調(diào)用了這個(gè)方法，就應(yīng)該獲得包含上述數(shù)據(jù)和一個(gè)說(shuō)明正確調(diào)用了的200響應(yīng)狀態(tài)碼。 同樣的,，一個(gè)不正確的調(diào)用應(yīng)該產(chǎn)生適當(dāng)?shù)?00 或500 響應(yīng)狀態(tài)碼和其它相關(guān)信息，以幫助用戶更好地操作。

請(qǐng)求

優(yōu)雅的處理復(fù)雜性

你試圖開放的數(shù)據(jù)包含大量的有利于用戶的屬性，這些屬性描述的基本資源和隔離特定信息，可以通過(guò)適當(dāng)?shù)姆椒▉?lái)操作。

一個(gè)API應(yīng)該努力提供完整的信息、數(shù)據(jù)和資源來(lái)幫助開發(fā)者以無(wú)縫的方式與之整合。

然而， 完整意味著對(duì)你的API考慮通用使用情況?？赡軙?huì)有許多這樣的關(guān)系和屬性,單獨(dú)為他們定義資源不是好的做法。

資源暴露的數(shù)據(jù)量也應(yīng)考慮。如果你暴露得太多，這會(huì)對(duì)服務(wù)器產(chǎn)生消極的影響，特別是對(duì)于負(fù)載和性能。

上述情況和關(guān)系是在設(shè)計(jì)的API時(shí)需要重點(diǎn)考慮的因素，可以使用適當(dāng)?shù)膮?shù)來(lái)處理。你可以掃描查詢參數(shù)中l(wèi)imit參數(shù)來(lái)限制響應(yīng)數(shù)據(jù)量，或者讓客戶端使用路徑參數(shù)來(lái)隔離數(shù)據(jù)。

以我們的照片分享應(yīng)用作為示例。

它可以用于開發(fā)者獲取在特定位置和特定主題標(biāo)簽中共享的所有照片的信息。 您可能還想要通過(guò)將每個(gè) API 調(diào)用的結(jié)果數(shù)限制為 10，以減輕服務(wù)器負(fù)載。 如果最終用戶想要找到波士頓的所有照片，并使用 winter 標(biāo)簽，則請(qǐng)求將是：

GET /photos?location=boston&hashtag=winter&limit=10 

注意現(xiàn)在的復(fù)雜性如何被簡(jiǎn)化為一個(gè)與查詢參數(shù)的簡(jiǎn)單關(guān)聯(lián)。如果您想根據(jù)客戶的請(qǐng)求提供特定用戶的信息，則調(diào)用：

GET /users/kesh92 

這里的 kesh92 是一個(gè)指定的用戶名，它會(huì)返回該用戶的地點(diǎn)和加入日期。

這只是朝著API完備性進(jìn)行參數(shù)設(shè)計(jì)的幾種方式，可以幫助用戶更直觀的使用你的API。

***， 有疑問(wèn)時(shí)，暫時(shí)離開它。如果你重新思考了某個(gè)資源或集合的功能，應(yīng)該把它放入下一個(gè)迭代中。開發(fā)和維護(hù)API是一個(gè)持續(xù)的過(guò)程，等待正確的用戶反饋可以構(gòu)建一個(gè)健壯的API，以幫助用戶以創(chuàng)造性的方式集成和開發(fā)應(yīng)用程序。

API設(shè)計(jì)入門

沒(méi)有一個(gè)API設(shè)計(jì)方法能夠一勞永逸解決所有組織的問(wèn)題。上述的建議僅僅是參考意見和建議，能否采用取決于你的用戶情況和需求。

一個(gè)API設(shè)計(jì)至關(guān)重要的主要原因是你的API能幫助到終端用戶，他們的需求就是貫穿你整個(gè)API設(shè)計(jì)的指明燈。