HTTP協議 - API開發經常使用部分

經常使用HTTP請求頭

• Accept 用來標明期待返回的數據格式以及請求API的版本號，例如application/vnd.site.v1+json
• Content-Type 用來標明POST或者PUT時HTTP的BODY內容格式，例如application/json
• Authorization 用來標明請求者的身份認證信息，例如Bearer 25877b47826645fdb5bf50b9be4d02fa

經常使用HTTP返回頭

• Link 用來表示資源相關的連接，在POST建立接口表示新建立資源的地址，在列表接口用來表示分頁首末頁地址
• X-Total-Count 用來表示分頁請求時總記錄的數量
• X-RateLimit-Limit 頻次限制爲多少次
• X-RateLimit-Remaining 頻次限制還差多少就觸發限制
• X-RateLimit-Reset 下一次頻次限制重置時間戳
• X-Request-ID 每一次請求惟一的ID
• Access-Control-Allow-Origin CORS容許全部的Ajax跨域請求，例如*
• Access-Control-Expose-Headers CORS容許JS讀取的返回頭，例如Link,X-Total-Count

經常使用HTTP狀態碼

• 200 ok 用來表示請求的資源以及對應的操做正確無誤的完成
• 201 created 用來表示POST要建立的資源建立成功
• 400 bad_request 用來表示通用的客戶端請求錯誤，沒有具體的明確意指，但能夠判斷是客戶端引發的錯誤
• 401 authentication_failed 用來表示身份認證的錯誤，即當前接口須要登錄後再請求但未從請求中獲取到身份信息
• 403 authorization_failed 用來表示受權類型的錯誤，即當前登錄用戶沒有權限執行該API操做
• 404 resource_not_found 用來表示請求的REST資源不存在，查證資源ID後再試
• 405 method_not_allowed 用來表示請求的REST資源不支持該HTTP Method，查證操做方法後再試
• 409 conflict 用來表示服務器存在的資源與要更新的資源存在衝突，沒法完成更新，請從新請求最新資源再更新
• 415 unsupported_media_type 用來表示Http Header指定的Accept類型未被支持，須要更換Accept類型
• 422 validation_failed 用來表示提交上來的數據沒有經過validation規則，須要求改投遞數據
• 429 too_many_requests 用來表示接口請求次數超限，須要暫緩請求，暫緩時間參考Retry-After的Header值
• 500 internal_error 用來表示接口出現了內部錯誤，極可能是未處理的異常事件，請通知API組進行處理
• 503 service_unavailable 用來表示服務暫時不可用，客戶端可稍後重試

Rest重要的幾條規範

• 使用專用域名
• URI使用中劃線、名詞複數（避免動詞）
• 合理使用查詢參數（避免uri層級過深、排序、分頁）
• 正確使用HTTP請求方法來處理CURD
• 優先在head中進行版本控制(Accept: application/vnd.github.v3+json)，其次在uri中處理(/v1)
• 無狀態協議，不得基於cookie、session，可以使用token替代
• 數據響應優先考慮json
• 對api進行限流
• 錯誤響應設計{code:xx, message:yy, description:可選錯誤描述, errors:[可選，校驗錯誤]}
• SSL加密（防止通訊數據，token等被竊聽）