介紹
其實對於我們接觸的web端開發而說，api就是協商好的一種規範，大家都按這個規範做事，這裡主要針對前&後端互動的介面進行說明～
返回值約定
返回值是指當前端返回後端給出的介面時返回的資料格式，常見的有這麼幾種：text, json, xml，現在大多數會用json，因為她傳輸資料少，可擴充套件性強，b格高～
方式一我們約定返回值如果包含errcode則視為有錯誤，並會出現可選的msg欄位，無錯誤則使用items表示迴圈的資料，格式如：
//提交成功，沒有返回資料
//獲取成功，返回列表資料
"items":[
"id": 1,
"name": "前端小武"
//獲取失敗，
"errcode": 1
//提交失敗
"errcode": 1,
"msg": "使用者名為空"
//返回乙個鏈結
"url": "/login/"
這種格式通常errcode會有乙個公用的錯誤碼，比如1001沒登入，2001使用者被鎖定等，注意的是這個值是強制型別，前端判斷：
function success (res) else else 獲取單個**資訊
顯式語義化風格
/api/photos/get-list 獲取**列表/api/photos/create 建立**/api/photos/delete 刪除**/api/photos/set 更新/api/photos/set-xx 更新某項/api/photos/get/ 建立單個
restful
rest是一種風格，也可以說是一種思想，現在已經被廣泛的應用於客戶端介面的開發，這是一種以提交型別來約定行為的，比如：
get /api/article 獲取所有的article列表get /api/article/10 獲取id為10的article詳細資訊post /api/article 新增乙個articleput /api/article/10 更新id為10的article資料delete /api/article/10 刪除id為10的article資料
ruanyifeng/blog/2014/05/restful_api.html
引數引數分必選和可選，分資料型別，字段說明，如：
引數名必選型別及範圍說明pagefalseint當前頁, 預設為1page_sizefalseint每頁多少條資料, 預設為20statustrueint**狀態, 1未開始, 2進行中, 3已完成, 4已刪除
文件介面文件常用的字段：
名稱，該介面的名稱備註，該介面的一些使用場景，注意問題等說明路徑，表明出訪問該介面的位址返回值格式，通常為json請求方式，請求該介面的方式引數，詳情列出介面需要的引數，分可選、必選返回字段說明，以文字描述出返回值比較重要的字段返回值例子，分多種狀態列出該介面可能出現的返回值
文件demo
版本控制
大版本小版本
服務API設計 之 API設計原則
對接xx業務時，xx業務具備的功能和api全靠跑業務負責人那反覆逐個詢問 確認。用哪個api 怎麼用 有沒有限制 等等 各個業務間，甚至同一業務內，api風格不統一。xx業務api效能方面未知。隨著業務的演進，開放的api持續在增加，但類同的很多 api編碼規範迫在眉睫 自解釋 易學習 易使用 難誤...
開放api設計
博主不大擅長寫作，但看了 高效能程式設計師的修煉 一書，不得不改變下自己。本文是對最近使用web service做專案時，討論的總結。如有錯誤，歡迎勘正，共同提高。第一次寫技術部落格，難免邏輯和條理不清，也請指點。本著分享和學習的目的，歡迎拍磚！主要分次三部分 restful風格 開放api的技術要...
api 設計良好 API 的特點
這裡 的 api 均為系統邊界的api設計，而對於內部 api 來說不在 範圍之內。變動困難 api 就像乙個人一樣，我們和乙個api打交道的時候需要了解這個人的特性偏好等，有的人很好相處，而有的人讓人很頭疼，尤其是你不得不和他打交道的時候。和人一樣，如果你不得不和他打交道，要改變他的秉性是很痛苦的...