用戶端通過HTTP協議與服務端交換資料

標籤：gen   http狀態代碼   present   als   安全防護   密鑰   字元   json   協議   

用戶端（包括瀏覽器）通過HTTP協議與服務端交換資料的描述發起請求http method

• 寫請求使用POST
• 讀請求使用GET

參數提交

• 提交一個普通對象，使用索引值對參數

  x-www-form-urlencoed

• 當同名參數有多個值時，使用http表單數組的方式

  • options[]:a
  • options[]:b
  • options[]:c
    …

• 當參數對應的值是複雜物件或多維陣列時，json序列化該對象/多維陣列

處理服務端響應預先準備

根據業務需求，確定當前響應返回的是業務資料，還是系統訊息。（此步驟不是代碼處理）

代碼處理

1. 檢查http狀態代碼。在檢查狀態代碼（例如：200。必鬚根據實際需求決定，此處只是舉例）後可能不再需要進一步處理並就此結束處理流程。
2. 如果響應返回的是業務資料，當http狀態代碼表明響應成功時，可從http body中讀取。
3. 如果響應返回的是系統訊息，可使用訊息代碼來確定訊息種類，再根據實際需求決定是否使用訊息描述及有效載荷。

API簽名機制

不需要簽名的會以 SignFree 標記。

1. 用請求參數產生索引值對，索引值對為“參數名=參數值”；其中上傳檔案的參數值為檔案內容sha1結果的小寫形式。
2. 所有索引值對按照鍵自然排序，然後用“&”串連為內容字串。
3. 使用內容字串產生待簽名字串，如“內容內容{應用ID}時間戳時間戳{應用密鑰}”。

   注意：${}表示預留位置。

4. 待簽名字串用sha1產生簽名，結果忽略大小寫。

操作結果狀態說明http狀態代碼

• 200 操作成功
• 400 請求有問題；如：表單驗證失敗、請求籤名驗證失敗等
• 401 認證失敗。
• 403 無存取權限。
• 409 請求處理完成但因為商務規則限制或其他原因並未真正成功的響應
• 500 伺服器錯誤
• 503 伺服器維護中

訊息結構

{"code":CODE,"msg":MSG,"payload":PAYLOAD}

• CODE：訊息代碼。字串，肯定不為空白。對一個API來說，訊息代碼用於區分訊息的種類，一旦確定就不再改變。
• MSG：訊息描述。字串。
• PAYLOAD：有效載荷。JSON對象或數組。

返回結果約定

• 凡是應該返回集合的操作，無結果時返回空集
• 均用JSON表示

安全防護

不是完全必須的，根據業務需求而定。

CSRF（跨站請求偽造） Token提交

1. 讀取服務端返回的名為 XSRF-TOKEN 的Cookie
2. 提交請求時，攜帶Token值
   • 通過HTTP header，X-XSRF-TOKEN
   • 通過系統級參數，_xsrf_token

應用ID、時間戳記、簽名提交

1. ID
   通過HTTP header ，X-CLIENT-ID。
   通過系統級參數，_clientId。

2. 時間戳記
   通過HTTP header ，X-TIMESTAMP。
   通過系統級參數，_timestamp。

3. 簽名
   通過HTTP header ，X-CLIENT-SIGN。
   通過系統級參數，_clientSign。

用戶端通過HTTP協議與服務端交換資料