設計優(yōu)秀的REST風格API非常困難！API是服務提供方和使用方之間的契約，打破該契約將會給服務端開發(fā)人員招來非常大的麻煩，這些麻煩來自于使用API的開發(fā)人員，因為對API的改動會導致他們的移動app無法工作。一個好的文檔對于解決這些事情能起到事半功倍的作用，但是絕對多數程序員都不喜歡寫文檔。
如果想讓服務端的價值更好的體現出來，就要好好設計API。通過這些API，你的服務/核心程序將有可能成為其他項目所依賴的平臺；目前的大公司：Facebook、Twitter、Google、Github、Amazon、Netflix等等無不依賴API，如果沒有精心設計的API對外開發(fā)它們的數據，這些公司也就不會像今天這么強大。事實上，整個產業(yè)存在的目的就是消費上述平臺提供的數據。
你提供的API越易用，就會有越多人愿意使用它。
如果在設計API時能遵循本文檔提出的原則，那么你設計出的API就能讓調用方更容易理解和使用，也能大幅減少調用方對你的抱怨；我已將文檔內容按主題分別進行詳細描述，讀者可選擇自己感興趣的主題，而無需順序閱讀。
本文檔中所使用的術語及其含義如下：
規(guī)劃API的展示形式可能比你想象的要簡單，首先要確定你的數據是如何設計以及核心程序是如何工作的？在新開發(fā)項目中進行API設計會比較容易，如果要對一個已經存在的項目進行修改使之符合REST風格，那么你就需要在抽象方面多下功夫了。[逍遙子筆記：按照RoyThomas Fielding對REST的設計，REST風格更適用于以數據為中心的架構，而非以計算為中心的架構]
有時，集合（Collection）可以表示數據庫里的一張表，資源（Resource）表示表中的一行。[逍遙子筆記：這里的比喻感覺有些不恰當，數據庫的一行對應的是一個資源實體，而非資源！]但是多數情況不是這樣簡單。事實上，你的API應該是對數據和業(yè)務邏輯的“盡可能的”抽象。非常重要的一點是：復雜的應用數據將會讓第三方開發(fā)人員理解和使用起來非常困難，如果你這么做了，他們就不想使用你的API了。[逍遙子筆記：設計API時，參數和返回值的數據不應太復雜，否則開發(fā)人員發(fā)起調用和處理返回結果時都要處理半天，非常麻煩！]
有些情況下，服務的數據不能通過API暴露出來。一個常見的例子就是許多API都不允許第三方開發(fā)人員創(chuàng)建用戶。[逍遙子筆記：設計API時，需要提供什么功能時就提供什么API出來，不要過早、過多暴露不必要的API接口，我們開發(fā)過程中通常會遇到這種情況：無論能否用到，先把自己服務的所有功能暴露出來再說，說不定就用上了，到時候就省得再修改了！]
你肯定知道HTTP的GET和POST請求，這是兩個通過瀏覽器訪問各種網頁時最常用的請求。術語POST甚至變成一個人們的常用語，即使不知道互聯網如何工作的用戶也知道能POST信息到朋友的Facebook留言板里。
你需要了解這里列出的4.5個非常重要的HTTP動作，這里的0.5個是指PATCH，因為它在功能上與PUT非常類似，剩下4個通常被API開發(fā)人員兩兩結合使用[逍遙子筆記：例如GET和POST，PUT和DELETE]。這里是這些動作以及它們對應的數據庫調用（我認為大多開發(fā)人員更熟悉數據庫操作而不是設計API）。[逍遙子筆記：正式基于作者的這個理解，所以本文的很多地方都是用數據庫來解釋API，其實這個也非常恰當，因為REST架構風格是基于資源的，而數據庫也是資源的一種形式。下面這些解釋中，括號里的內容就是與該HTTP動詞類似的數據庫操作]
還有兩個不常見的HTTP動作：
一個優(yōu)秀的API將會充分利用這4.5個HTTP動作讓第三方開發(fā)人員與自己的數據交互，并且URL中決不包含動作/動詞。[逍遙子筆記：URL是對資源描述的抽象，資源的描述一定是名詞，如果引入了動詞，那這個URL就表示了一個動作，而非一個資源，這樣就偏離了REST的設計思想]
通常，GET請求能夠被瀏覽器緩存（而且通常都會這么做），例如，當用戶發(fā)起第二次POST請求時，緩存的GET請求（依賴于緩存首部）能夠加快用戶的訪問速度。一個HEAD請求基本上就是一個沒有返回體的GET請求，因此也能被緩存。
無論你在設計什么系統(tǒng)，也不管你事先做了多么詳盡的計劃，隨著時間的推移和業(yè)務的發(fā)展，你的程序總會發(fā)生變化，數據關系也會發(fā)生變化，資源可能會被添加或者刪除一些屬性。只要軟件還在生存期內并且還有人在用它，開發(fā)人員就得面對這些問題，對于API設計來說，尤其如此。[逍遙子筆記：根據RoyThomas Fielding對資源的解釋：資源描述和資源實體是分開的，而設計REST API是基于資源描述，當資源實體發(fā)生變更時，只要修改資源描述和資源實體的映射，就能保證資源描述不變，進而保證所設計的API不變，所有使用API的第三方程序也不需要做任何修改，因此，REST風格就是用于解耦這種服務端和客戶端的關系]
API是一份調用方（Consumer）和服務器之間已達成的契約，更改服務器的API必然會影響其向后兼容性，對契約的破壞將會招致使用方（Consumer）的抱怨，如果你改動很大，他們可能會放棄使用你的服務。為了確保服務器程序能夠進化升級，同時能夠讓使用方感到滿意，你需要在引入新版本API的同時繼續(xù)讓舊版本的API正常工作。
注意，如果你只是簡單地為API增加一些新特性，例如為資源增加新屬性（這些新屬性并非必須的，沒有它們資源也能工作），或者新增了端點，那就不需要升級API的版本號，因為這些變化并不會破壞向后的兼容性。當然，你還是需要更新API設計文檔（你和調用方的契約）。[逍遙子筆記：文檔對于API來說太重要了，沒有好的文檔必然沒有好的API，因此API和它的文檔一定同步修改，甚至要先修改文檔]
過一段時間之后，你可以告訴調用方不建議（deprecate）使用舊版本[逍遙子筆記：就像java里面的depredated注釋一樣，用于告訴使用方，我不建議你使用它了，過一段時間之后我可能就不支持它了]。不建議使用一個API并不意味著馬上就要關閉它或者降低它的服務質量，而是告訴你的API使用人員他們需要版本升級，舊的版本將在未來一段時間之后被停止服務。[逍遙子筆記：通過過渡期來提醒用戶升級API，明確告訴調用方什么API處在過渡期，過渡期內新老版本同時都能工作，但老版本在過渡期之后就會被去掉]
在URL中加入版本號是一個優(yōu)秀的API設計，當然還有另一個常用的解決辦法就是把版本號放在請求首部中[逍遙子筆記：HTTP請求的accept字段]，根據多年與第三方開發(fā)人員打交道的經驗，我可以告訴你把版本號放在URL里要比放在請求的首部中更容易實現和使用。[逍遙子筆記：對這種方法還有一些疑問，個人理解，版本應該標識資源，也就是版本是針對URL尾部的端點，例如https：//api.example.com/vi/zoos中的/zoos，按照這種思路，當一個項目包含很多類型的資源，這些資源需要要分級進行展示，此時版本號放在URL里可能遇到很多問題，例如：有個即時通信項目IM，它包含user_info（用戶信息），user_rel（用戶關系），message三個資源大類，其中user_info又分為公開信息public和私有信息private兩個類型，public類型包括個人簡介的二維碼信息self_info，private類型包括個人的應用鎖信息lock， user_rel（用戶關系）類型包括好友關系friends和群組groups兩個類型，groups包含群成員member和群信息info兩個子類型資源，messge包含新聊天消息new和歷史聊天消息history，這些資源組織成樹狀結構后如下圖所示：
假設我的URL根（在本文后面將會介紹URL的根）為：https：//test.jason.com/im/*，那么上述資源對應的URL為：
（1）https：//test.jason.com/im/user_info/public/self_info
該URL表示資源：用戶個人簡介的二維碼信息；
（2）https：//test.jason.com/im/user_info/private/lock
該URL表示資源：用戶的應用鎖信息；
（3）https：//test.jason.com/im/user_rel/friends
該URL表示資源：用戶的好友信息
（4）https：//test.jason.com/im/user_rel/groups/member
該URL表示資源：群組的群成員
（5）https：//test.jason.com/im/user_rel/groups/info
該URL表示資源：群組的信息
（6）https：//test.jason.com/im/message/new
該URL表示資源：用戶新聊天消息
（7）https：//test.jason.com/im/message/history
該URL表示資源：用戶的歷史聊天消息
問題是：在這種情況下版本號應該放在URL的那個地方？
如果版本號是針對IM整個項目，例如這里的IM項目整體分為v1和v2兩個大版本，此時的URL首部就能改成：https：//test.jason.com/im/v1/*，https：//test.jason.com/im/v2/*，實際的URL資源將變成：https：//test.jason.com/im/v1/message/new。
如果版本號是針對IM項目中的某個子類，例如這里的message類型分為v1和v2兩個版本，那么消息類的URL根就會變成：https：//test.jason.com/im/message/v1/*，https：//test.jason.com/im/message/v2/*，實際的URL資源將會變成：https：//test.jason.com/im/message/v1/new。
如果版本號針對的資源類型更詳細，那么版本號就會更靠后。在一些負責類型的項目中，資源的類型也會非常復雜，層級也更深，按照本文作者建議的方法就很難確定v1的位置]
跟蹤各版本/端點的API被調用的情況[逍遙子筆記：由此可見版本號對應URL末尾的“端點”]?？梢酝ㄟ^在數據庫中為每個API增加一個計數器來實現，來一個請求就將對應的使用計數加1。統(tǒng)計各API的調用情況會帶來很多好處，例如，優(yōu)化調用頻度最高的API。
為了構建第三方開發(fā)人員喜歡的API，最重要事情是確定何時不建議（deprecate）用戶使用舊版本API，你可以使用這些不建議的（deprecated）API來告知第三方開發(fā)人員，這是在你廢掉舊版本之前提醒他們的一個好途徑。
通知第三方開發(fā)人員的過程可以自動化完成，例如，每調用10，000次deprecated API就給相應開發(fā)人員發(fā)一個郵件提醒。
無論你是否相信，API的根設計非常重要。當開發(fā)人員接手一個使用你的API所開發(fā)的舊項目，并且需要為它增加新特性的時候，他可能完全不了解你的服務，或許他們知道的就是所調用的一系列URL。重要的是你API的URL根應該盡可能簡單，一個又長又復雜的URL看起來就嚇人，它很可能就把這些第三方開發(fā)人員嚇跑了。
這里有兩個普通的URL根：
如果你的應用程序很龐大，或者未來它可能變得很龐大，你可以把API放在各自的子域內，這么做可以讓你的程序在以后的發(fā)展中更靈活、更容易擴展。[逍遙子筆記：這里作者想表達的意思好像是把URL所表示的資源進行分類、分層級，不同的資源放在不同的類中]
如果你的程序不會變得這么大，或者你想簡化程序的使用（例如，你想通過一個框架同時提供網站和API服務），就把你的API放在URL的根域（例如：/api/）之后。
最好讓你API的根也包含內容。例如，訪問githubAPI的根就會得到一個端點（端點代表資源）列表。我更偏好使用根URL獲取那些對“正在迷茫中的”開發(fā)人員來說有用的信息，例如：怎么獲取API的開發(fā)者文檔。
注意使用HTTPS前綴，一個好的RESTfulAPI必須使用HTTPS作為前綴。[逍遙子筆記：例如：https://api.example.com/v1/zoos]
端點是URL中用于標識一個特定資源或資源集合的那部分URL片段。[逍遙子筆記：例如：https://api.example.com/v1/zoos中的/zoos]
假如你想構建用于表示多個動物園資源的API，其中，每個動物園都包含很多動物（每個動物只能屬于一個動物園），顧員（他們可以在多個動物園工作），并且需要跟蹤每個動物的詳細信息，那么這些API的端點可能如下所示：[逍遙子筆記：下列URL中紅色加粗的后綴就是端點]
在介紹這些端點的作用時，你需要給出這些端點以及操作它們的HTTP動作。例如下面給出的是剛才所構建動物園API列表的功能，注意，我在每個端點前面都加上了HTTP動作，就像HTTP請求中所使用的那樣。
上述列表中，ZID表示動物園的ID，AID表示動物ID，EID表示雇員ID，ATID表示動物類型ID，在文檔中給出關鍵詞及含義是一個非常好的習慣。
在上面的例子中我已簡要列出常見API的URL前綴，這種簡化方式（省略URL前綴）非常有利于溝通，但是在你的API文檔當中，還是要使用全部的URL（例如：GET https://api.example.com/vi/animal_type/ATID）。[逍遙子筆記：在非正式文檔中介紹一個API時可以采用端點代替完成URL這種方法：HTTP動作+端點+該端點的功能說明，端點要比完整URL短的多，這樣更容易表述，也不影響理解，但是在正式文檔中還是要把URL寫全]
這里需要注意數據之間關系的展示，尤其是雇員和動物園之間的多對多的關系。你可以通過增加URL的方式來表示更多的數據關系[逍遙子筆記：根據RoyThomas Fielding對資源的解釋，關系也是一種資源，因此，在遇到多對多的數據關系時，可以將數據關系進行拆分，并為每個關系都增加一個URL]。當然，這里并沒有一個HTTP操作能表示解除雇員，但是我們可以通過刪除指定動物園的雇員的方式來達到同樣的效果。[逍遙子筆記：這是對上面“DELETE/zoos/ZID/employees/EID：解雇指定動物園的某個雇員”這個條目的解釋]
當用戶請求獲取一組對象列表時，你就需要對結果進行過濾并返回一組嚴格符合用戶要求的對象。有時返回結果的數量可能非常大，但是你也不能隨意對此進行約束，因為這種服務端的隨意約束會造成第三方開發(fā)人員的困惑。如果用戶請求了一個集合，并對返回結果進行遍歷，然后只要前100個對象，那么這里就需要由用戶來指明這個限制量。這樣用戶就不會有這樣的疑惑：是他們程序的bug還是接口限制了100條？還是網絡只允許傳這么大的包？[逍遙子筆記：在IM項目中有個接口讓用戶拉取自己的歷史消息，我們就需要在接口中增加一個參數讓用戶來確定本次要拉取多少條歷史消息，服務器端根據用戶傳入的限制量來確定返回消息的條數，而不是由服務器來在實現時就確定該接口一次調用只能返回幾條]
盡量減少對第三方開發(fā)人員的隨意約束。[逍遙子筆記：不要在接口中添加默認的約束條件]
非常重要的一點：讓第三方開發(fā)人員自己指定排序過濾器/返回結果集的約束條件。這么做的最重要原因是：用戶能用盡量少的網絡消耗盡快獲取到結果；第二個重要原因是：用戶可能很懶，想讓服務端幫他們做好分頁和過濾；還有一個對客戶端不那么重要，但是對服務端很重要的原因：這么做會降低請求的資源負載。
過濾器通常用于過濾GET請求返回的資源集合，在GET請求中，可以通過URL傳遞過濾器信息。你可以放心把下面例子中列出的過濾器類型應用到自己的API中：
上述部分過濾器與前面介紹的某些URL端點功能重復，例如前面提到的URL：GET /zoo/ZID/animals在功能上就與使用過濾器的GET /animals?zoo_id=ZID重復。功能單一的端點對于第三方開發(fā)人員來說更容易使用，尤其是他們使用你提供的請求做一些復雜的開發(fā)時，更是如此。在API文檔中明確寫出這些功能重復的請求方式，將會消除第三方開發(fā)人員對這些重復功能的困惑，否則他們就會懷疑這些重復功能之間是否有差異！
還有一點，當需要對數據進行過濾或者排序時，你要給第三方開發(fā)人員（Consumer）列出哪些屬性能用于過濾或排序，我們不希望把任何數據庫操作的錯誤返回給用戶。[逍遙子筆記：不要把服務內部的錯誤或者問題暴露給第三方開發(fā)人員]
充分利用適當的狀態(tài)碼對于設計REST 風格的API來說非常重要，因為HTTP狀態(tài)碼已有標準定義，并且各種網絡設備都能讀取并識別這些它們。例如，通過配置負載均衡器的參數來避免將請求發(fā)往出現50X錯誤的服務程序[逍遙子筆記：50X表示服務程序內部出錯]。這里將列出一些可供你選擇使用的HTTP狀態(tài)碼，它們可以成為你設計良好返回碼的出發(fā)點：
客戶端向服務器請求數據時，服務器找到這些數據并將之返回給客戶端（此行為冪等）；[逍遙子筆記：GET操作只能獲取數據（即只讀），不應該對服務器的數據進行任何形式的修改]
客戶端向服務器發(fā)送數據，服務器為這些數據創(chuàng)建一個資源；
客戶端請求服務器刪除一個資源時，服務器將該資源刪除；[逍遙子筆記：返回碼204表示執(zhí)行成功了，但是沒有數據。HTTP 的RFC2616中對于204返回碼的描述為：如果客戶端是個代理（例如瀏覽器），它不應該改變“觸發(fā)該請求的”頁面展示，該返回值主要用于輸入行為發(fā)生時，雖然新的或更新過的元數據信息被應用于當前頁面，但代理（瀏覽器）不能改變當前的頁面展示，原文為：
If the client is a user agent, itSHOULD NOT change its document view from that which caused the request to besent. This response is primarily intended to allow input for actions to takeplace without causing a change to the user agent’s active document view,although any new or updated metainformation SHOULD be applied to the documentcurrently in the user agent’s active view.]
客戶端給服務器發(fā)送了一個無效的請求，服務器對此不作任何動作（此行為冪等）。
客戶端請求了一個不存在的資源或資源集合，服務端對此不作任何動作（此行為冪等）。
服務器內部發(fā)生了錯誤，客戶端無法知道請求是否被執(zhí)行成功了。
1XX的返回碼預留給HTTP的底層使用，在你的整個職業(yè)生涯中都不會主動發(fā)送這種返回碼；
2XX的返回碼表示請求按照預期執(zhí)行并成功返回了信息。服務端要盡可能給用戶返回這種結果。
3XX的返回碼表示請求重定向，大多數API都不會經常使用這種請求（），但是最新的超媒體API會充分使用這些功能。
4XX的返回碼主要表示由客戶端引起的錯誤，例如請求參數錯誤或者訪問一個不存在的資源，這些必須為冪等操作，并且不能改變服務器的狀態(tài)[逍遙子筆記：其實服務器的狀態(tài)發(fā)生了改變就意味著操作不是冪等了]。
5XX的返回碼主要表示由服務器引起的錯誤，通常情況下，這些錯誤都是開發(fā)人員（[逍遙子筆記：這里應該是服務器程序的開發(fā)人員]）接觸不到的底層函數拋出來，然后傳遞給用戶（[逍遙子筆記：這里應該是第三方開發(fā)人員]）的。用戶在收到5XX的返回碼時，他們不知道服務器當前的工作狀態(tài)是否正常，因此，要盡量避免這種情況發(fā)生。
當第三方開發(fā)人員在發(fā)送HTTP請求時，他們需要事先了解這些請求的返回值信息，下述列表就是一些REST風格API以及它們對應的返回值信息：[逍遙子筆記：與前面的介紹URL的功能類似，只是這里將最后面的URL描述換成返回值描述，這里依然采用三段式描述法：HTTP請求動作+端點+端點對應的返回值描述信息]
需要注意的是：當用戶創(chuàng)建一個資源時，他們通常并不想知道新創(chuàng)建資源的ID（也不想知道其他屬性，例如修改或創(chuàng)建的時間戳）[逍遙子筆記：這一點略有疑惑，這種設計思路應該也是區(qū)分場合的，如果資源很復雜，本文介紹的這種思路或許可行，如果資源原本就很簡單，例如我們以前設計的發(fā)送消息接口，就直接給用戶返回所發(fā)送消息的ID]。這些新增的屬性信息可通過后續(xù)請求獲得，當然也可以通過初始化POST請求來返回。
多數情況下，服務器想確切知道每個請求的發(fā)起方是誰？當然，部分API接口能放開被用匿名訪問，但通常接口只能被授權的用戶訪問。
OAuth2.0為此提供了一個很好的實現途徑。你能知道每個請求是由哪個客戶端發(fā)起？這些請求背后分別代表了哪些用戶？以及提供一種標準化的用戶訪問或撤銷訪問方式，所有這些都無需第三方用戶的登錄授信。
還有OAuth1.0和xAuth也能完成類似功能。無論采用那種方法，一定要確保通用性以和良好的文檔設計，在文檔中對用戶常用語言/平臺的各種不同封裝庫進行詳細說明。[逍遙子筆記：這些服務以庫的方式供客戶端調用，例如SDK，因此在文檔中要對各種形式的封裝庫進行詳細說明]
我可以如實地告訴你，盡管OAuth1.0a雖然是最安全的選項，但是它非常難以部署。我遇到很多第三方開發(fā)人員抱怨他們不得不實現自己的庫，因為OAuth1.0a沒有他們所使用語言對應的庫。我花費了大量的時間用于解決那些難以理解的“invalid signature”錯誤。因此，我建議你使用其他的替代方案。
目前，大多數REST風格API接口都提供JSON格式的數據，你所能想起來的Facebook、Twitter、GitHub都是如此。XML方式已經逐漸退出人們的視野（除了一些大公司內部還在使用之外），幸虧SOAP方式已經消失，我們已經看不到返回HTML格式數據的API接口了。
開發(fā)者常用的開發(fā)語言或框架都能輕易解析你返回的各種有效數據。如果你正在使用不同的序列化器構建一個通用的返回對象，你可以使用前面提到的任意數據格式（SOAP除外），不過在返回數據時需要注意處理請求首部的Accept字段。[逍遙子筆記：HTTP請求頭部的Accept可用于指定返回數據的格式]
一些API開發(fā)人員建議針對不同返回內容的類型，為URL（在端點之后）添加擴展字段，例如：.json，.xml，或者.html，但我不建議這么做，我建議使用HTTP請求首部的Accept字段（HTTP的RFC文檔中有對Accept的解釋），并且覺得這才是合適的方法。
超媒體API可能代表REST風格API的未來發(fā)展，它們在思想上更符合HTTP和HTML的設計初衷。[逍遙子筆記：根據REST作者Roy Thomas Fielding的描述，REST核心是面向資源的設計，超媒體服務所提供了各種多媒體資源的訪問，它在本質上符合了以資源為中心的設計]
在使用非超媒體的REST風格API時，URL端點也是客戶端和服務器之間契約的一部分，這些端點必須事先告知客戶端，一旦改變它們，客戶端就無法按預期與服務器進行交互，這其實也是一種約束。
現在，API的用戶不僅僅是能發(fā)起HTTP請求的用戶代理，人們更常用瀏覽器發(fā)起HTTP請求。然而，用戶不會被這些預先定義的、REST風格API的URL端點所約束。是什么讓用戶變得如此特殊呢？現在的網頁能讓用戶先讀主題，然后點擊他們感興趣的主題所對應的鏈接，訪問他們想訪問的網站或者想閱讀的內容，此時URL發(fā)生變化的時候，用戶不受影響（除非用戶為某個網頁打了標簽，在他們訪問這些打了標簽的網頁時會自動跳轉到主頁，用戶需要再從主頁中尋找他們所感興趣數據的新路徑）。[逍遙子筆記：我們的網站通常采用這種方式，尤其是各種門戶網站，例如網易：www.163.com，新浪:www.sina.com，打開這些門戶網站，我們看不到一個URL，我們所看到的都是一個個的主題，每個主題對應一個超鏈接（URL），當這些主題對應的URL發(fā)生變化時，只需要調整主題和超鏈接（URL）的映射關系即可，用戶實際上看不到這些URL的變化]
超媒體API概念和一個普通人的行為類似。請求API的根目錄將會獲得一個URL列表，這些URL列表的每一項都可能對應了一個信息集，并且它以用戶能夠理解的方式來描述這些信息集合。無需為每個資源提供ID（除非特別邀請），因為一個URL就唯一標識了一個資源。
超媒體API用戶在訪問連接并且收集信息時，返回結果中將被放入最近更新的URL鏈接，因此URL無需事先與用戶約定。如果URL被緩存了，后續(xù)請求又返回了404[逍遙子筆記：404表示請求了一個不存在的資源]，用戶只需簡單地回到根目錄重新尋找內容即可。
當從集合中檢索一個資源列表時，要給用戶返回這個資源列表的完整URL。當執(zhí)行POST/PATCH/PUT請求時，可用返回碼為3XX的響應來重定向到新的資源。
JSON即無法給我們提供需要的語義來指明哪些屬性是URL，也不能說明URL怎樣與當前的文檔關聯起來；可能正如你猜測的那樣，HTML可以提供這樣的信息。我們可以先通過API拿到數據，然后再進行HTML處理。想想CSS陪伴我們走過的這些路，我們可能有一天會看到：在獲取同樣URL和內容的時候，無論通過API請求還是網站訪問，都采用同一種處理方式。[逍遙子筆記：JSON提供數據內容，并未提供數據展示功能]
老實說，如果沒有完全按照本文檔的指導，你的API也不一定會太差，然而，如果你沒有為API編寫合適的文檔，沒有人會愿意用它，它將變?yōu)橐粋€極難使用的API。
確保你的文檔無需授權便可被開發(fā)人員訪問。
不要使用自動文檔生成器，如果用了，就一定要仔細檢查和修改生成的文檔，確保它們能夠被用戶理解和使用。
文檔中所舉例子中的請求和響應包體要寫全，不要截斷不重要的部分，而是用高亮方式展示重要的部分。
文檔中要寫明各URL端點的預期返回碼和可能的出錯信息，以及出現這些錯誤信息的可能原因是什么？
如果時間充足，你還可以構建一個第三方開發(fā)人員使用的API控制臺，以便他們可以立即對你的API進行驗證。這個事情做起來不會像你想象的那么難，但是開發(fā)人員（包括內部開發(fā)人員和第三方開發(fā)人員）卻可能因為這個功能而喜歡上使用你的API。
確保文檔能被打印，例如，CSS就是一種強大的文檔展示方式；在文檔打印的時候一定要隱藏文檔的工具欄，即便沒有人把你的文檔用打印機打印出來，也會有很多開發(fā)人員喜歡把它們輸出為PDF以便離線查看。
