僅備忘：

1. 第一章　概述

隨著網際網路的發展，網站應用的規模不斷擴大，常規的垂直應用架構已無法應對，分散式服務架構勢在必行。

u 單一應用架構

Ø 當網站流量很小時，只需一個應用，將所有功能都部署在一起，以減少部署節點和成本。

u 垂直應用架構

Ø 當訪問量逐漸增大，單一應用增加機器帶來的加速度越來越小，將應用拆成互不相干的幾個應用，以提升效率。

u 分散式服務架構

Ø 當垂直應用越來越多，應用之間互動不可避免，將核心業務抽取出來，作為獨立的服務，逐漸形成穩定的服務中心，使前端應用能更快速的響應多變的市場需求。

本規範旨在為公司各業務系統之間業務複用及整合的API提供介面呼叫與互動規範。同時，也作為未來公司業務系統內各應用模組之間以及各業務系統之間，基於面向服務的架構，以服務介面的方式，提供資料和各種功能的一種嘗試。

本規範僅適用於由伺服器端發起呼叫請求、POST提交資料以及GET請求文字資料結果的API，統一採用UTF-8編碼規則，採用JSON格式響應。

1. 

2. 

3. 

4. 

API 服務介面提供如下REST風格的HTTP介面：

http://api.xxx.com/yyy/zzz?{query_string}

query_string由系統級引數部分和具體API呼叫引數部分組成，以key1=value1&key2=value2&…表示，對於採用POST請求的Open API，query_string部分則是在POST請求體裡。所有查詢類的API介面既支援POST，也支援GET方式，提交類的API介面僅支援POST方式。

1.   

2.   

3.   

4.   

4.1.   

4.2.   

以下引數是由API平臺系統定義的，各系統需要支援這些引數以便接入該平臺提供開放介面。API平臺系統採用應用授權認證介面方式，合作初始API平臺系統代第三方系統申請應用分配accessid和金鑰accesskey。

API系統級引數

各業務系統應遵守API平臺系統規範中應用級通用引數的約定。

應用級引數的通用約定

Ø  過程描述

傳送方將引數等進行HMAC演算法計算，將得到的雜湊值（即簽名值）與請求的引數一同提交至接收方，然後接收方再次將引數等值進行HMAC演算法計算，將得到的雜湊值與你傳遞過來的雜湊值進行核對驗證，若一樣，說明請求正確、驗證通過，進行一下步工作，若不一樣，將返回錯誤。

以如下請求為例，說明sign簽名的生成步驟：

http:// api.xxx.com/yyy/zzz?accessid=1234&uid=abc&time=1361431471&sign=XXXXXX

Ø  步驟一：構造源串

1. 將除”sign”以外的所有請求引數按key進行字典升序排列，將除Host標頭(域名

+埠)外的apiname和排序後的引數(key=value)用&拼接起來，如：

/yyy/zzz?accessid=1234&uid=abc&time=1361431471

注意：如果請求中沒有apiname，則在生成簽名時，不需要加入apiname。如上示例，

可改為：accessid=1234&uid=abc&time=1361431471

2. 將上述生成的字串進行URL編碼（參見本章節最後URL編碼注意事項，否則容

易導致後面簽名不能通過驗證）。

       步驟二：生成sign值

       1. 使用HMAC-SHA1加密演算法，將accessid對應的私鑰accesskey作為引數，對從

步驟一得到的源串進行加密；

2.將上述加密後的字串進行Base64編碼。

注意：生成的簽名中可能包含“=”，因此需要再進行一次URL編碼。

執行完上述步驟，即可獲得簽名串，作為sign的值。

URL編碼注意事項

URL編碼規則：

簽名驗證時，要求對字串中除了“-”、“_”、“.”之外的所有非字母數字字元都替換成百分號(%)後跟兩位十六進位制數。

十六進位制數中字母必須為大寫。

注意事項：

1. 某些系統方法，例如.NET系統方法HttpUtility.UrlEncode會將‘=’編碼成‘%3d’，而不是%3D，導致加密簽名通不過驗證。Java早期版本中，呼叫java.net.URLEncoder下的方法進行URL編碼時，某些特殊字元如“*”不會被編碼，而不是“%2A”，會導致生成的簽名不能通過驗證。因此，需開發人員手動編碼，否則將導致加密簽名一直通不過驗證。

2. 某些語言的urlencode方法會把“空格”編碼為“+”，實際上應該編碼為“%20”。這也將生成錯誤的簽名，導致簽名通不過驗證。請開發人員手動將“+”替換為“%20”。

在PHP中，推薦用rawurlencode方法進行URL編碼。

{

string accessid = "1234";

string accesskey ="YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY";

   string time =System.DateTime.Now.ToString("yyyyMMddHHmmss");

string value = "";

string queryString = "";

//準備引數

SortedDictionary<string, string>paramlist = new SortedDictionary<string, string>();

paramlist.Add("city","1");

paramlist.Add("countyName","海淀區");

paramlist.Add("buildName", "新浪大廈");

paramlist.Add("status","2");

paramlist.Add("timestamp",timestamp);

//拼接字串

foreach (KeyValuePair<string, string>kvp in paramlist)

{

value += kvp.Key + kvp.Value;

queryString += "&" +kvp.Key + "=" + Utf8Encode(kvp.Value);

}

StringBuilder sb = new StringBuilder();

sb.Append(apiKey);

sb.Append(value);

sb.Append(apiSecret);

value = sb.ToString();

string url ="http://api.xxx.com/build/getbuildinfo?apikey=" + apiKey +"&timestamp=" + timestamp + "&apisign=" +SHA1(value) + queryString;

int status = 0;

Console.WriteLine(url);

Console.WriteLine(RequestUrl(url, outstatus));

Console.ReadLine();

}

執行結果顯示如下（僅演示，中間略過RequestUrl(url, out status)具體執行）：[a1] 

注意：請確保介面與呼叫者的字串編碼一致，最好統一使用utf-8編碼，如果編碼方式不一致則計算出來的簽名會校驗失敗。

1.   

2.   

3.   

4.   

5.   

API當前僅支援JSON響應格式，正常響應包符合如下規範的json字串：

l  http響應頭中的Content-Type指定為application/json, charset=utf-8

l  字串編碼格式是UTF-8

l  輸出格式為：

｛

       "StatusCode": "錯誤碼（數值型）",

       "StatusMsg": "錯誤描述（字元型）"

  ,

   [Response Body]

}

(*) [Response Body] 可為空。

錯誤響應輸出內容符合以下規範：

l  返回內容包含在json輸出格式”Status”中，由StatusCode、StatusMsg這2個屬性組成，分別用於描述錯誤碼以及錯誤資訊。

以下為json輸出格式示例：

{

      "StatusCode": 0,

       "StatusMsg": "Success"

    ,

   "Body": {

       "ID": 2,

       "Name": "新浪大廈",

       "Description": {

            "CityName": "北京",

            "CountyName": "海淀",

            "Business": "中關村",

           "Address": "中關村大街甲59號文化大廈1007"

       },

       "Fit": "豪裝",

       "AvgDailyRent": 500,

       "MainImage": "http://192.168.1.1:7000/LP/2015/09/14/Tb/20150914163059_6404.jpg"

   }

}

API平臺系統API呼叫過程中可能會返回的錯誤碼定義如下表所示：

注：錯誤碼隨API細化，會逐漸增多，當前為規則說明。

以下為API介面細則參考：

 [a1]簽名演算法調整，待修改示例程式碼