在移動互聯網的時代, Web服務已經成為了異構系統之間的互聯與集成的主要手段，各種 Web服務幾乎都采用REST風格的Web Api來構建。 通過Http協議的形式來. 以Get/Post方式發送請求, 返回json格式(數據更小巧且自描述能力強)的數據。這里就不在介紹REST API 的好處和不足。這些網上一大堆資料。今天就說說，如何構建優秀的REST API ？
目前，各大互聯網公司, 對自身的REST Api設計有各自的標准，他們的Api 的設計也非常成熟。 那么，我們應該如何更好的設計我們的接口， 來提高我們 API 的可用性，易用性，可維護性與可擴展性呢？
一. API 設計方案
1. Http的請求分為URL約定規則、請求參數規則
URL規則: http://{server}/{product}/{version}/{logic}/{method}?{query_string}
server: 為具體的服務域名
product: 為應用工程名
version: 為具體版本號, 便於將來的功能擴展, 可以暫定為 v1, v2
logic: 為具體業務邏輯的初步划分, 比如后端管理方法, app端的請求方法
method: 具體業務的方法
具體的請求參數, 由指定的method方法決定, 全都作為HTTP GET/POST的參數列表。
這里很多人會問為什么把 method 和 version 放到在URI中？
因為這樣可以使API 版本化，方便版本控制，同時也便於日后API的分流。當然關於是否將版本信息放入url還是放入請求頭里面，曾經有過很激烈的爭論，各有各的道理。我個人認為放到 URL 中會好一些。具體的大家還是根據自己的業務場景，綜合考量吧。
2. Http的響應規則
HTTP響應碼為200, 返回結果為JSON字符串的形式:
如果響應結果正確,則返回結果如下所示:
{
data : { // 請求數據，對象或數組均可
user_id: 123,
user_name: "zwz",
user_avatar_url: "http://www.abc.com/1.jpg"
...
},
msg : "done", // 請求狀態描述，調試用
success : 1,
code" : 1001, // 業務自定義狀態碼
extra : { // 其他擴展的數據，字段、內容不定
type: 1,
desc: "簽到成功！"
}
}
如果響應結果失敗,則返回如下結果:
{
data : { // 請求數據，對象或數組均可
},
msg : "Internal Server Error", // 請求狀態描述，調試用
success : 0,
code : 5001, // 業務自定義狀態碼
extra : {
}
}
3. Auth 權限驗證
API 的權限驗證，有很多方案，目前成熟的OAuth 2.0框架等，不過 ，最簡單的還是利用 Http Header 來完成這一目標。 將token 通過 Header 傳遞。來實現權限驗證。
4. API 在設計的時候，最好不要將業務錯誤碼與HTTP狀態碼的綁定,重新定義一套業務錯誤碼，來區分HTTP 的狀態碼。
狀態碼的定義也最好有一套規范，類似於HTTP 的狀態碼，可以按照用戶相關、授權相關、各種業務，做簡單的分類。
// Code 業務自定義狀態碼定義示例
// 授權相關
1001: 無權限訪問
1002: access_token過期
1003: unique_token無效
...
// 用戶相關
2001: 未登錄
2002: 用戶信息錯誤
2003: 用戶不存在
// 業務相關
3001: 業務XXX
3002: 業務XXX
// 系統異常
5001：Internal Server Error
二. 其他一些建議：
1. 規范統一的命名
使用駝峰式或者下划線格式都可以，統一規范就行。不過，目前基本都是統一小寫加下划線比較好。如：user_id，user_name，user_age等。
2. 語義清晰，遵守常用縮寫
字段的名字最好能體現字段的類型，遵守一些常用的縮寫，如：user_name, task_desc, date_str 等
3. 空值、空字段的處理
空值、空字段的處理也是比較容易出問題。統一空值用null 。除了布爾類型的，其余的空值統一用null表示，客戶端保證每種字段的null可以被正常處理。
4. 各個Action 盡量符合CRUD操作的原則。
5. 給不同類型設置默認空值
除了null，盡量對字段設置“默認值”，如數字就是0，字符串就是空字符串""，數組就是空數組[]，對象就是空對象{}，這樣可以避免客戶端處理空值產生的異常。
具體的要根據業務、前后端約定而定。
比如，bool 類型的值，統一成數字0和1 。時間日期類型強制只能傳標准GMT/UTC時間戳，然后由各自的客戶端根據自己的時區、顯示要求做處理后顯示。
6. 完整的URL
API里面的數據也會有URL類型的，一般來說如用戶的頭像、各種圖片、音頻等資源，都是以URL鏈接的形式返回的。
返回的URL一定要“完整”，主要指的是不要忘記URL里面的協議部分。應該是http://www.abc.com/1.jpg。
7. REST 安全
可以使用固有的 HTTP 基本驗證，你還可以考慮通過支持表單驗證，LTPA 驗證，Open ID 驗證等方式，來滿足更多的企業安全要求。
8. 盡量將API部署在專用域名之下。例如：https://api.example.com。
9. API返回的數據格式，應該盡量使用JSON，避免使用XML。
10. 返回正確 HTTP 響應代碼,同時重新定義一套業務錯誤碼，來區分HTTP 的狀態碼。
11. 完善的文檔，最好能自動生成在線API文檔，這樣文檔能隨時保持最新。
目前有很多自動生成API 文檔的攻擊，例如：SwaggerUI。