一、介面規則：

二、狀態碼規範

204 No Content

如果更新成功，且客戶端屬性保持最新，伺服器必須返回204 No Content狀態碼。適用於PUT請求，以及僅調整links，不涉及其它屬性的POST, DELETE請求

200 OK

如果伺服器接受更新，但是在請求指定內容之外做了資源修改，必須響應200 OK以及更新的資源例項，像是向此URL發出GET請求.

201 Created

如果伺服器需要建立一些資源, 比如建立使用者, 建立使用者資料, 建立資源, 預設API的create方法返回這個狀態碼.

301 Moved Permanently

被請求的資源已永久移動到新位置, 適用於資源link的變更,伺服器做出相容API.

303 See Other

對應當前請求的響應可以在另一個 URI 上被找到，客戶端應該使用 GET 方法進行請求, 適用於舊API往新API的相容.

400 Bad Request

請求體包含語法錯誤, 出現本錯誤服務端應該向客戶端傳送出錯描述

適用於:

• 傳送了無法轉化的請求體

需要驗證使用者身份，如果伺服器就算是身份驗證後也不允許客戶訪問資源，應該響應 403 Forbidden, 適用於未登入檢查

403 Forbidden

伺服器拒絕執行

適用於:

• 服務到期（比如付費的增值服務等）
• 因為某些原因不允許訪問（比如被 ban ）
• 許可權不夠，403 狀態碼

404 Not Found

找不到目標資源

適用於:

• 需要修改的資源不存在

405 Method Not Allowed

不允許執行目標方法，響應中應該帶有 Allow 頭，內容為對該資源有效的 HTTP 方法

406 Not Acceptable

伺服器不支援客戶端請求的內容格式（比如客戶端請求 JSON 格式的資料，但伺服器只能提供 XML 格式的資料）

409 Conflict

請求操作和資源的當前狀態存在衝突

410 Gone

被請求的資源已被刪除

412 Precondition Failed

伺服器在驗證在請求的頭欄位中給出先決條件時，沒能滿足其中的一個或多個。主要使用場景在於實現併發控制

413 Request Entity Too Large

POST 或者 PUT 請求的訊息實體過大

415 Unsupported Media Type

伺服器不支援請求中提交的資料的格式

422 Unprocessable Entity

請求格式正確，但是由於含有語義錯誤，無法響應

適用於:

• 傳送了非法的資源

428 Precondition Required

要求先決條件，如果想要請求能成功必須滿足一些預設的條件 適用於:

• 缺少了必要的頭資訊

500 Internal Server Error

伺服器遇到了一個未曾預料的狀況，導致了它無法完成對請求的處理。

501 Not Implemented

伺服器不支援當前請求所需要的某個功能。 501 與 405 的區別是：405 是表示服務端不允許客戶端這麼做，501 是表示客戶端或許可以這麼做，但服務端還沒有實現這個功能

502 Bad Gateway

作為閘道器或者代理工作的伺服器嘗試執行請求時，從上游伺服器接收到無效的響應。

503 Service Unavailable

由於臨時的伺服器維護或者過載，伺服器當前無法處理請求。這個狀況是臨時的，並且將在一段時間以後恢復。如果能夠預計延遲時間，那麼響應中可以包含一個 Retry-After 頭用以標明這個延遲時間（內容可以為數字，單位為秒；或者是一個 HTTP 協議指定的時間格式）。如果沒有給出這個 Retry-After 資訊，那麼客戶端應當以處理 500 響應的方式處理它。

適用於: 伺服器維護中

三、安全規範

1.簽名演算法

簽名生成的通用步驟如下：

第一步，設所有傳送或者接收到的資料為集合M，將集合M內非空引數值的引數按照引數名ASCII碼從小到大排序（字典序），使用URL鍵值對的格式（即key1=value1&key2=value2…）拼接成字串stringA。 特別注意以下重要規則：

• 引數名ASCII碼從小到大排序（字典序）；
• 如果引數的值為空不參與簽名；
• 引數名區分大小寫；
• 驗證呼叫返回或主動通知簽名時，傳送的sign引數不參與簽名，將生成的簽名與該sign值作校驗。
• 介面可能增加欄位，驗證簽名時必須支援增加的擴充套件欄位

第二步，在stringA最後拼接上key得到stringSignTemp字串，並對stringSignTemp進行MD5運算，再將得到的字串所有字元轉換為大寫，得到sign值signValue。

舉例，假設傳送的引數如下：

<?php
$id = '380840976';
$author_id = '1000000';
$body = 'test';
$date = gmdate('D, d M Y H:i:s \G\M\T');

第一步：對引數按照key=value的格式，並按照引數名ASCII字典序排序如下：

<?php
$stringA= "id=".$id."&author_id=".$author_id."&body=".$body."&date=".$date;

第二步：拼接API金鑰並進行簽名：

<?php
$stringSignTemp=$stringA."&key=302006259b3c09247ec02edaf64f6a5f";
$sign=strtoupper(MD5($stringSignTemp));

最終得到最終傳送的資料

2.傳送請求

將上一步生成的簽名，放到 HTTP 訊息頭中。如果沒有簽名或者簽名錯誤，則會導致介面呼叫失敗，服務端會返回 HTTP 狀態碼 401

格式如下：

<?php
$headers = [
        "Date: ".$date, // header 中使用的時間必須和生成簽名的時間$date相同
        "Authorization: Blogchina $appid:".$sign,//$appid 為開發者申請的appid
    ];
$body = [
    'id'=>$id,
    'author_id'=>$author_id,
    'body'=>$body,
    'date'=>$date,
];

$response = Unirest\Request::post("http://api.blogchina.com/", $headers, $body);
$response->raw_body;

3.回撥API安全

在普通的網路環境下，HTTP請求存在DNS劫持、運營商插入廣告、資料被竊取，正常資料被修改等安全風險。使用者回撥介面使用HTTPS協議可以保證資料傳輸的安全性。所以建議使用者回撥採用HTTPS協議。