狀態(tài)代碼和錯(cuò)誤代碼是指響應(yīng)頭中的代碼號(hào)，用于指示響應(yīng)的常規(guī)分類，例如，請(qǐng)求是否成功（200），是否導(dǎo)致服務(wù)器錯(cuò)誤（500），是否存在授權(quán)問題（403），等等。標(biāo)準(zhǔn)狀態(tài)代碼通常不需要太多文檔，但是特定于您的API的自定義狀態(tài)和錯(cuò)誤代碼則需要。錯(cuò)誤代碼特別有助于解決不良請(qǐng)求。
目錄
- curl標(biāo)頭中的狀態(tài)碼示例
- 列出HTTP響應(yīng)和錯(cuò)誤碼的位置
- 在哪里獲取狀態(tài)和錯(cuò)誤碼
- 如何列出狀態(tài)碼
- 狀態(tài)/錯(cuò)誤代碼可以幫助進(jìn)行故障排除
- 狀態(tài)和錯(cuò)誤碼示例Context.ioTwitterMailchimpFlickr
- 具有狀態(tài)和錯(cuò)誤代碼的活動(dòng)
curl標(biāo)頭中的狀態(tài)碼示例
狀態(tài)碼未出現(xiàn)在響應(yīng)正文中。它們顯示在響應(yīng)標(biāo)題中，默認(rèn)情況下您可能看不到。還記得您在“curl調(diào)用方法”中提交了curl調(diào)用嗎？要獲取響應(yīng)頭，請(qǐng)?jiān)赾url請(qǐng)求中添加--include或-i。如果您只想在響應(yīng)中返回響應(yīng)標(biāo)頭（而不要返回其他任何內(nèi)容），請(qǐng)大寫-I，如下所示：
curl -I -X GET "https://api.openweathermap.org/data/2.5/weather?zip=95050&Appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial"
響應(yīng)頭如下所示：
HTTP/1.1 200 OKServer: openrestyDate: Thu, 06 Dec 2018 22:58:41 GMTContent-Type: application/json; charset=utf-8Content-Length: 446Connection: keep-aliveX-Cache-Key: /data/2.5/weather?units=imperial&zip=95050Access-Control-Allow-Origin: *Access-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST
第一行HTTP / 1.1 200 OK告訴我們請(qǐng)求的狀態(tài)（200）。大多數(shù)REST API都遵循響應(yīng)頭的標(biāo)準(zhǔn)協(xié)議。例如，200不僅僅是OpenWeatherMap API開發(fā)人員確定的任意代碼。200是用于成功HTTP請(qǐng)求的通用代碼。（如果您更改方法，則會(huì)獲得其他狀態(tài)代碼。）
有了GET請(qǐng)求，很容易判斷請(qǐng)求是否成功，因?yàn)槟鷷?huì)獲得預(yù)期的響應(yīng)。但是，假設(shè)您要進(jìn)行POST，PUT或DELETE調(diào)用，那么您將在其中更改資源中包含的數(shù)據(jù)。您如何知道API是否成功處理并接收了請(qǐng)求？響應(yīng)標(biāo)頭中的HTTP響應(yīng)代碼將指示操作是否成功。HTTP狀態(tài)代碼只是較長(zhǎng)消息的縮寫。
狀態(tài)代碼非常微妙，但是當(dāng)開發(fā)人員使用API??時(shí)，這些代碼可能是開發(fā)人員擁有的唯一“接口”。如果您可以
狀態(tài)碼通常不提供信息，編寫得很差，并且很少或沒有向用戶傳達(dá)有用的信息來(lái)克服該錯(cuò)誤。最終，狀態(tài)碼應(yīng)幫助用戶從錯(cuò)誤中恢復(fù)。
您可以在此處查看常見的REST API狀態(tài)代碼列表，并在此處查看HTTP狀態(tài)代碼的常規(guī)列表。盡管最好包含一些標(biāo)準(zhǔn)狀態(tài)代碼，但是不需要全面記錄所有標(biāo)準(zhǔn)狀態(tài)代碼，尤其是在您的API很少觸發(fā)的情況下。
列出HTTP響應(yīng)和錯(cuò)誤碼的位置
大多數(shù)API應(yīng)該有一個(gè)通用頁(yè)面，其中列出了整個(gè)API的響應(yīng)和錯(cuò)誤代碼。一個(gè)單獨(dú)的頁(yè)面列出了狀態(tài)代碼（而不是在每個(gè)端點(diǎn)中包括這些狀態(tài)代碼），使您可以更詳細(xì)地?cái)U(kuò)展每個(gè)代碼，而不會(huì)占用其他文檔。它還減少了冗余和信息過(guò)載感。
另一方面，如果某些端點(diǎn)比其他端點(diǎn)更容易觸發(fā)某些狀態(tài)和錯(cuò)誤代碼，則在相同的API參考頁(yè)面上突出顯示這些狀態(tài)和錯(cuò)誤代碼是有意義的。一種策略可能是引起注意特定端點(diǎn)的任何特別相關(guān)的狀態(tài)或錯(cuò)誤代碼，然后鏈接到集中的“響應(yīng)和狀態(tài)代碼”頁(yè)面以獲取完整信息。
在哪里獲取狀態(tài)和錯(cuò)誤代碼
在記錄API時(shí)，狀態(tài)代碼和錯(cuò)誤代碼可能并不明顯。您可能需要向開發(fā)人員索要API獨(dú)有的所有狀態(tài)和錯(cuò)誤代碼的列表。有時(shí)，開發(fā)人員會(huì)直接在編程代碼中對(duì)這些狀態(tài)和錯(cuò)誤代碼進(jìn)行硬編碼，而沒有簡(jiǎn)單的方法來(lái)向您提供完整的列表（這也使本地化成為問題）。結(jié)果，您可能需要嘗試一下以找出所有代碼。
具體來(lái)說(shuō)，您可能需要嘗試破壞API才能查看所有潛在的錯(cuò)誤代碼。例如，如果您超出了特定呼叫的速率限制，則API可能會(huì)返回特殊錯(cuò)誤或狀態(tài)代碼。您尤其需要記錄此自定義代碼。API中的疑難解答部分可能會(huì)特別使用錯(cuò)誤代碼。
如何列出狀態(tài)碼
您可以在基本表或定義列表中列出狀態(tài)和錯(cuò)誤代碼，如下所示：
狀態(tài)/錯(cuò)誤代碼可以幫助進(jìn)行故障排除
狀態(tài)和錯(cuò)誤代碼在進(jìn)行故障排除時(shí)特別有用。因此，您可以將這些錯(cuò)誤代碼視為故障排除部分的補(bǔ)充。幾乎所有的文檔集都可以從故障排除一節(jié)中受益。
在故障排除主題中，您記錄了當(dāng)用戶走開快樂的道路并在黑暗的森林中迷路時(shí)發(fā)生的情況。狀態(tài)代碼就像照明不佳的步道標(biāo)志一樣，可以幫助用戶回到正確的道路上。
有關(guān)疑難解答的一節(jié)可能列出與以下情況有關(guān)的錯(cuò)誤消息：
- 使用了錯(cuò)誤的API密鑰
- 使用了無(wú)效的API密鑰
- 參數(shù)不適合數(shù)據(jù)類型
- API引發(fā)異常
- 沒有數(shù)據(jù)可返回的資源
- 已超出速率限制
- 參數(shù)超出了可接受的最大值和最小值范圍
- 端點(diǎn)缺少必需的參數(shù)
盡可能在文檔中記錄錯(cuò)誤的確切文本，以便在搜索時(shí)輕松顯示該錯(cuò)誤。
狀態(tài)和錯(cuò)誤代碼示例
以下是API文檔中的一些示例狀態(tài)和錯(cuò)誤代碼頁(yè)。
Context.io
Context.io狀態(tài)和錯(cuò)誤代碼
Clearbit不僅記錄了標(biāo)準(zhǔn)狀態(tài)碼，而且還描??述了其API返回的唯一參數(shù)。大多數(shù)開發(fā)人員可能會(huì)熟悉200、400和500的代碼，因此這些代碼不需要太多解釋性的細(xì)節(jié)。但是，如果您的API具有唯一的代碼，請(qǐng)確保充分描述它們。
Twitter狀態(tài)和錯(cuò)誤代碼
借助Twitter的狀態(tài)代碼文檔，他們不僅可以描述代碼和狀態(tài)，還可以提供有用的故障排除信息，從而可能有助于錯(cuò)誤恢復(fù)。例如，對(duì)于500錯(cuò)誤，作者不只是說(shuō)狀態(tài)是指服務(wù)中斷，他們還解釋說(shuō)：“這通常是暫時(shí)的錯(cuò)誤，例如在高負(fù)載情況下，或者端點(diǎn)暫時(shí)有問題。如果其他人遇到類似問題，請(qǐng)登錄開發(fā)者論壇，或者稍后再試。”
這種有用的信息是技術(shù)作者應(yīng)針對(duì)狀態(tài)代碼（至少對(duì)于那些指示問題的代碼）的目標(biāo)。
Mailchimp
Mailchimp狀態(tài)和錯(cuò)誤代碼
Mailchimp提供了錯(cuò)誤消息的可讀且友好的描述。例如，對(duì)于403錯(cuò)誤，Mailchimp不僅僅是寫“ Forbidden”，還解釋了為什么您可能會(huì)收到Forbidden代碼的原因。使用Mailchimp，有幾種類型的403錯(cuò)誤。您的請(qǐng)求可能由于用戶帳戶被禁用或?qū)﹀e(cuò)誤的數(shù)據(jù)中心的請(qǐng)求而被禁止。對(duì)于“ WrongDataCenter”錯(cuò)誤，Mailchimp指出“它通常與配置錯(cuò)誤的庫(kù)相關(guān)聯(lián)”，并且它們鏈接到有關(guān)數(shù)據(jù)中心的更多信息。這是對(duì)用戶有用的錯(cuò)誤代碼文檔。
Flickr
Flickr的狀態(tài)和錯(cuò)誤代碼
使用Flickr，“響應(yīng)代碼”部分嵌入在每個(gè)API參考主題中。因此，描述簡(jiǎn)短。在每個(gè)主題中嵌入響應(yīng)代碼會(huì)使錯(cuò)誤代碼更明顯，但在某些方面卻沒有太大幫助。因?yàn)樗度朐诿總€(gè)API主題中，所以有關(guān)錯(cuò)誤代碼的描述必須簡(jiǎn)短，否則內(nèi)容將使端點(diǎn)請(qǐng)求信息不堪重負(fù)。
相比之下，列出錯(cuò)誤代碼的獨(dú)立頁(yè)面使您可以在不排擠其他文檔的情況下更詳細(xì)地?cái)U(kuò)展每個(gè)代碼。獨(dú)立頁(yè)面還可以減少冗余并減少大量信息（只是重復(fù)的信息）的顯示。
如果某些端點(diǎn)比其他端點(diǎn)更容易觸發(fā)某些狀態(tài)和錯(cuò)誤代碼，則在其相關(guān)的API參考頁(yè)上突出顯示這些狀態(tài)和錯(cuò)誤代碼是有意義的。建議您注意端點(diǎn)頁(yè)面上任何特別相關(guān)的狀態(tài)或錯(cuò)誤代碼，然后鏈接到集中頁(yè)面以獲取完整信息。
具有狀態(tài)和錯(cuò)誤代碼的活動(dòng)
使用您確定的開源項(xiàng)目，確定狀態(tài)和錯(cuò)誤代碼信息?；卮鹨韵聠栴}：
- 項(xiàng)目是否描述狀態(tài)和錯(cuò)誤代碼？狀態(tài)和錯(cuò)誤代碼信息在文檔上下文中位于何處？作為獨(dú)立主題？在每個(gè)端點(diǎn)之下？別的地方？
- API是否具有任何唯一的狀態(tài)和錯(cuò)誤代碼？
- 錯(cuò)誤代碼是否可以幫助用戶從錯(cuò)誤中恢復(fù)？
- 向其中一個(gè)端點(diǎn)發(fā)出請(qǐng)求。然后有意地更改參數(shù)，以使其無(wú)效。響應(yīng)中返回什么狀態(tài)碼？是否記錄了此狀態(tài)碼？
