參考
https://www.kancloud.cn/liupeizhi/openapi/292276
https://blog.csdn.net/qq_41961113/article/details/80347341
https://www.cnblogs.com/xiezhi/p/6434812.html
正確規(guī)范寫接口文檔
前言
正規(guī)的團(tuán)隊(duì)合作或者是項(xiàng)目對(duì)接杯拐，接口文檔是非常重要的遂赠，一般接口文檔都是通過開發(fā)人員寫的箍镜。一個(gè)工整的文檔顯得是非重要咪奖。下面我總結(jié)下自己看到的優(yōu)秀接口文檔系宫。
接口規(guī)范內(nèi)容
接口名稱
場景說明
接口說明
請求參數(shù)
響應(yīng)參數(shù)
錯(cuò)誤碼
參數(shù)內(nèi)容
字段名
變量名
是否必填
類型
示例值
描述
錯(cuò)誤碼內(nèi)容
名稱
描述
原因
解決方案
一.銀聯(lián)接口文檔示例 （適用于接口規(guī)范文件）
5.2.2 統(tǒng)一收單線下交易查詢
5.2.2.1 場景說明
收單機(jī)構(gòu)可以通過該接口主動(dòng)查詢訂單狀態(tài)靶壮，完成下一步的業(yè)務(wù)邏輯从诲。需要調(diào)用查詢接口的情況:
當(dāng)收單機(jī)構(gòu)后臺(tái)、網(wǎng)絡(luò)契耿、服務(wù)器等出現(xiàn)異常瞒大，收單機(jī)構(gòu)系統(tǒng)最終未接收到支付通知;調(diào)用支付接口后，返回系統(tǒng)錯(cuò)誤或未知交易狀態(tài)情況;調(diào)用alipay.trade.pay宵喂，返回INPROCESS的狀態(tài);調(diào)用alipay.trade.cancel之前糠赦，需確認(rèn)支付狀態(tài)。
5.2.2.2 接口說明
公共請求參數(shù)中的method填寫alipay.trade.query锅棕。
5.2.2.2.1 請求參數(shù)
參數(shù) 參數(shù)名 類型 是否必填 最大長度 描述 示例值
out_trade_no 商戶訂單號(hào) String 否 32 訂單支付時(shí)傳入的商戶訂單號(hào),和網(wǎng)聯(lián)交易號(hào)不能同時(shí)為空拙泽。trade_no,out_trade_no如果同時(shí)存在優(yōu)先取trade_no 20150320010101001
... ... ... ... ... ... ...
trade_no 網(wǎng)聯(lián)交易號(hào) String 否 64 網(wǎng)聯(lián)交易號(hào)，和商戶訂單號(hào)不能同時(shí)為空 2014112611001004680073956707
5.2.2.2.2 響應(yīng)參數(shù)
參數(shù) 參數(shù)名 類型 是否必填 最大長度 描述 示例值
trade_no 網(wǎng)聯(lián)交易號(hào) String 是 64 網(wǎng)聯(lián)交易號(hào) 2013112011001000000121536
... ... ... ... ... ... ...
out_trade_no 商戶訂單號(hào) String 是 32 商戶訂單號(hào) 6823789339978240
TradeFundBill字段說明:
參數(shù) 參數(shù)名 類型 是否必填 最大長度 描述 示例值
fund_channel 資金渠道 String 是 32 交易使用的資金渠道 ALIPAYACCOUNT
... ... ... ... ... ... ...
5.2.2.3 錯(cuò)誤碼
錯(cuò)誤碼 錯(cuò)誤描述 原因 解決方案
SYSTEMERROR 接口返回錯(cuò)誤 系統(tǒng)超時(shí) 請不要更換商戶退款單號(hào)裸燎，請使用相同 參數(shù)再次調(diào)用 API顾瞻。
NOTENOUGH 余額不足 商戶可用退 款余額不足 此狀態(tài)代表退款申請失敗，商戶可根據(jù) 具體的錯(cuò)誤 示做相應(yīng)的處理德绿。
... ... ... ...
二.API開發(fā)接口文檔示例 （適用于http荷荤、https 接口）
3.1.1 查詢排重接口
3.1.1.1 場景說明
查詢信息是否已存在退渗。
3.1.1.2 接口詳情
3.1.2.1 接口地址
接口詳情
地址 http://www.baidu.com （正式環(huán)境）
請求方式 GET
3.1.2.2 參數(shù)
參數(shù) 是否必填 說明
idfa 是 廣告標(biāo)識(shí)符
... ... ...
source 是 渠道來源，具體值在接入時(shí)再進(jìn)行分配
3.1.2.3 返回結(jié)果
返回結(jié)果 格式 JSON
狀態(tài)碼 10000 success（調(diào)用成功）
... ...
10010 access prohibited(訪問拒絕)
3.1.1.3 調(diào)取示例
3.1.1.3.1 查詢成功
{
"state": 10000,
"message": "success",
"data": {
"BD239708-2874-417C-8292-7E335A537FAD": 1 //已經(jīng)存在
}
}
{
"state": 10000,
"message": "success",
"data": {
"BD239708-2874-417C-8292-7E335A537FAD": 0 //不存在
}
}
3.1.1.3.2 接口調(diào)用失敗
{
"state": 10010,
"message": "access prohibited",
"data": [
]
}
本文來自 qq_41961113 的CSDN 博客 蕴纳，全文地址請點(diǎn)擊：https://blog.csdn.net/qq_41961113/article/details/80347341?utm_source=copy
一会油、什么是接口文檔？
在項(xiàng)目開發(fā)中古毛，web項(xiàng)目的前后端分離開發(fā)翻翩，APP開發(fā)，需要由前后端工程師共同定義接口稻薇，編寫接口文檔嫂冻，之后大家都根據(jù)這個(gè)接口文檔進(jìn)行開發(fā)，到項(xiàng)目結(jié)束前都要一直維護(hù)塞椎。
二桨仿、為什么要寫接口文檔？
1案狠、項(xiàng)目開發(fā)過程中前后端工程師有一個(gè)統(tǒng)一的文件進(jìn)行溝通交流開發(fā)
2服傍、項(xiàng)目維護(hù)中或者項(xiàng)目人員更迭，方便后期人員查看莺戒、維護(hù)
三伴嗡、接口規(guī)范是什么急波？
首先接口分為四部分：方法从铲、uri、請求參數(shù)澄暮、返回參數(shù)
1名段、方法:新增(post) 修改(put) 刪除(delete) 獲取(get)
2、uri：以/a開頭泣懊，如果需要登錄才能調(diào)用的接口(如新增伸辟、修改；前臺(tái)的用戶個(gè)人信息馍刮，資金信息等)后面需要加/u信夫，即：/a/u；中間一般放表名或者能表達(dá)這個(gè)接口的單詞卡啰；get方法静稻，如果是后臺(tái)通過搜索查詢列表，那么以/search結(jié)尾匈辱，如果是前臺(tái)的查詢列表振湾，以/list結(jié)尾；url參數(shù)就不說了亡脸。
3押搪、請求參數(shù)和返回參數(shù)树酪，都分為5列：字段、說明大州、類型续语、備注、是否必填
字段是類的屬性厦画；說明是中文釋義绵载；類型是屬性類型，只有String苛白、Number娃豹、Object、Array四種類型购裙；備注是一些解釋懂版，或者可以寫一下例子，比如負(fù)責(zé)json結(jié)構(gòu)的情況躏率，最好寫上例子躯畴，好讓前端能更好理解；是否必填是字段的是否必填薇芝。
4蓬抄、返回參數(shù)結(jié)構(gòu)有幾種情況：1、如果只返回接口調(diào)用成功還是失敽坏健（如新增嚷缭、刪除、修改等）耍贾，則只有一個(gè)結(jié)構(gòu)體：code和message兩個(gè)參數(shù)阅爽；2、如果要返回某些參數(shù)荐开，則有兩個(gè)結(jié)構(gòu)體：1是code/mesage/data付翁，2是data里寫返回的參數(shù),data是object類型；3晃听、如果要返回列表百侧，那么有三個(gè)結(jié)構(gòu)體，1是code/mesage/data,data是object能扒，里面放置page/size/total/totalPage/list 5個(gè)參數(shù)佣渴，其中l(wèi)ist是Arrary類型，list里放object赫粥，object里是具體的參數(shù)观话。
注意：uri地址里不允許出現(xiàn)大寫字母，如果是兩個(gè)單詞拼接越平，用/分開
不懂接口的程序員就不懂開發(fā)
開發(fā)人員的面試中频蛔，面試者常常描述不清做過的項(xiàng)目灵迫。原因很簡單，要么你不懂接口晦溪，要么你描述不清接口瀑粥。描述接口有兩個(gè)重點(diǎn)，稱為2P：一是協(xié)議（Protocol）三圆，二是原型（Prototype）狞换，它們分別描述..
本文來自 爪哇_怪盜基德 的CSDN 博客 ，全文地址請點(diǎn)擊：https://blog.csdn.net/qq_40140473/article/details/78220845?utm_source=copy
開發(fā)人員的面試中舟肉，面試官經(jīng)常會(huì)讓你描述之前做過的一些項(xiàng)目修噪，以及你在其中開發(fā)的部分÷访模看似很簡單黄琼，很多人就是講不清楚，要么寥寥幾句講不清楚整慎，要么東扯西湊不著重點(diǎn)脏款。原因很簡單，要么你不懂接口裤园，要么你描述不清接口撤师。
小白面試者：“我做過手機(jī)開發(fā)，最近一個(gè)項(xiàng)目是個(gè)在線訂餐的APP拧揽，我做的用戶下單剃盾，訂單列表這塊功能∏糠ǎ”
資深面試官：“好万俗，說說你是怎樣從后臺(tái)取一個(gè)用戶的訂單列表的∫樱”
小白：“調(diào)一個(gè)函數(shù)。嚎研。蓖墅。呃，就從后臺(tái)取到數(shù)據(jù)临扮。论矾。。然后顯示到頁面上杆勇√翱牵”
資深：“調(diào)什么樣的函數(shù)，它是怎么與后臺(tái)通訊的蚜退？后臺(tái)返回的數(shù)據(jù)是什么樣子闰靴？”
小白：“調(diào)ajax彪笼，后臺(tái)會(huì)返回一個(gè)數(shù)組。蚂且。配猫。”
資深心想：“呵呵杏死，啥叫后臺(tái)返回?cái)?shù)組泵肄，接口協(xié)議的過程完全不清楚。問問看接口原型能不能講清楚淑翼「玻”，問：“數(shù)組的具體數(shù)據(jù)結(jié)構(gòu)你能描述一下嗎玄括？”
小白：“就是一個(gè)變量系忙。。惠豺。沒有結(jié)構(gòu)啊银还。。洁墙∮挤瑁”
資深（心想）：“捉急啊，數(shù)據(jù)類型也講不清楚热监，真奇怪應(yīng)用是怎么做出來的捺弦。。孝扛×泻穑”
一個(gè)表達(dá)良好且真實(shí)做過這塊開發(fā)的程序員，應(yīng)該有能力描述出細(xì)節(jié)：前端通過HTTP協(xié)議發(fā)出請求苦始，調(diào)用這樣的語句$.get("api/queryOrder?status=1")寞钥，可以用參數(shù)status表示只取指定狀態(tài)的訂單，后端返回JSON格式的數(shù)據(jù)陌选，它表示是一個(gè)數(shù)組理郑，數(shù)組每一項(xiàng)是個(gè)訂單（Order類型），訂單的屬性有整型的id, 數(shù)值型的總價(jià)total等咨油。
重點(diǎn)抓到了嗎您炉？首先他是大體知道通訊協(xié)議（HTTP/JSON等），并且可以詳細(xì)描述出怎樣調(diào)用后臺(tái)役电；其次赚爵，對(duì)這次調(diào)用，他可以清楚的描述出了參數(shù)和返回值的類型、含義這些細(xì)節(jié)冀膝，對(duì)原型有一定描述能力唁奢。
而他可能對(duì)HTTP協(xié)議的細(xì)節(jié)不太了解。如果是個(gè)愛鉆研或資深些的開發(fā)畸写，可以把HTTP協(xié)議交互的細(xì)節(jié)講清楚：
前端以HTTP GET方式向后端發(fā)出請求驮瞧，發(fā)送請求像這樣：
GET api/queryOrder?status=1
1
其中，應(yīng)用層定義網(wǎng)址中枯芬，queryOrder是調(diào)用名论笔，status是調(diào)用函數(shù)，參數(shù)通過urlencoded方式傳遞千所。后端成功時(shí)返回?cái)?shù)據(jù)像這樣：
200 OK
[{id:1, dscr:"order 1", total:100}, {id:2, dscr:"order 2", status:1}]
1
2
3
能說到這個(gè)程度狂魔，接口協(xié)議這一塊已經(jīng)很懂了。如果再遇到抽象能力強(qiáng)的淫痰，會(huì)直接寫出形式化的接口原型最楷，像這樣：
queryOrder(status) -> [ {id, dscr, total} ]
1
那么這已經(jīng)是精通前后端通訊的架構(gòu)師水平了。
看到這里待错，新手會(huì)若有所思籽孙，但還是不禁要問，“到底啥叫接口火俄？是Java里面那個(gè)Interface關(guān)鍵字嗎犯建？”沒錯(cuò)，接口的英文是Interface瓜客。不過它不局限于是一個(gè)關(guān)鍵字适瓦，而是一組設(shè)計(jì)思想：
把待開發(fā)對(duì)象的接口理清楚，就決定了你對(duì)需求的理解程度和設(shè)計(jì)方案的方向正確性谱仪，其實(shí)就是需求分析和概要設(shè)計(jì)玻熙，它也同時(shí)決定了測試設(shè)計(jì)的質(zhì)量。
把對(duì)象的內(nèi)部接口理清楚（劃分模塊疯攒，理清它們之間的交互）嗦随，決定了方案的實(shí)現(xiàn)，其實(shí)就是詳細(xì)設(shè)計(jì)和編碼的工作卸例。
代碼寫亂了称杨，已經(jīng)難以理解了，這時(shí)要使用接口分離筷转，這叫重構(gòu)。
怎樣才能把接口描述清楚呢悬而？描述接口有兩個(gè)重點(diǎn)呜舒，稱為2P：一是協(xié)議（Protocol），二是原型（Prototype）笨奠，它們分別描述了交互的方式與內(nèi)容袭蝗。協(xié)議說的是唤殴，調(diào)用方和被調(diào)用方是怎樣交互的，比如基于HTTP協(xié)議到腥，請求參數(shù)用urlencoded格式朵逝，返回內(nèi)容用JSON格式；原型描述的是一個(gè)請求的內(nèi)容乡范，調(diào)用名稱配名，參數(shù)和返回內(nèi)容是什么含義，以及類型晋辆。
大到軟件工程渠脉，小到編寫個(gè)去后臺(tái)獲取訂單列表的函數(shù)，多半的時(shí)間都花在確定接口和實(shí)現(xiàn)接口上瓶佳。
下一節(jié)芋膘，我再和大家聊聊各種接口以及每種接口的表示。
本文來自 天笑2001 的CSDN 博客 霸饲，全文地址請點(diǎn)擊：https://blog.csdn.net/skyshore/article/details/50995163?utm_source=copy
我們此次后端api的實(shí)現(xiàn)主要是按照RESTful api規(guī)范來設(shè)計(jì)的为朋，就是符合REST架構(gòu)下設(shè)計(jì)api的規(guī)范。簡單的來說REST結(jié)構(gòu)就是：利用URL定位資源厚脉，用HTTP動(dòng)詞(GET,POST,PUT,DELETE)來描述相應(yīng)操作习寸。
RESTful api主要的意義在于它可以讓在不同形式的前端所接受到的用戶請求能夠統(tǒng)一的發(fā)送到一個(gè)后臺(tái)并返回不同的前端。RESTful api是由后端SERVER實(shí)現(xiàn)并提供給前端來調(diào)用的一個(gè)接口器仗。前端調(diào)用API來向后臺(tái)發(fā)起HTTP請求融涣，后臺(tái)響應(yīng)請求并將處理結(jié)構(gòu)反饋給前端。所以說RESTful是典型的基于HTTP的協(xié)議精钮。所以下面我們對(duì)RESTful api的設(shè)計(jì)原則與規(guī)范進(jìn)行相應(yīng)的說明：
一威鹿、協(xié)議
API與用戶的通信協(xié)議，總是使用HTTPs協(xié)議轨香。
二忽你、域名
盡量將API部署在專用域名之下：
三、版本
將我們API的版本號(hào)放入U(xiǎn)RL中：
四臂容、路徑
路徑又稱"終點(diǎn)"（endpoint）科雳，表示API的具體網(wǎng)址。
在RESTful架構(gòu)中脓杉，每個(gè)網(wǎng)址代表一種資源（resource）糟秘，所以網(wǎng)址中不能有動(dòng)詞，只能有名詞球散，而且所用的名詞往往與數(shù)據(jù)庫的表格名對(duì)應(yīng)尿赚。一般來說，數(shù)據(jù)庫中的表都是同種記錄的"集合"（collection），所以API中的名詞也應(yīng)該使用復(fù)數(shù)凌净。
舉例來說悲龟，有一個(gè)API提供動(dòng)物園（zoo）的信息，還包括各種動(dòng)物和雇員的信息冰寻，則它的路徑應(yīng)該設(shè)計(jì)成下面這樣：
https://api.jupiter.com/zoo
https://api.jupiter.com/animals
https://api.jupiter.com/employees
五须教、HTTP動(dòng)詞
對(duì)于資源的具體操作類型，由HTTP動(dòng)詞來表示斩芭，常用的HTTP動(dòng)詞有下面五個(gè)(括號(hào)中對(duì)應(yīng)的是相應(yīng)的SQL命令)：
GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）轻腺。
POST（CREATE）：在服務(wù)器新建一個(gè)資源。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）秒旋。
PATCH（UPDATE）：在服務(wù)器更新資源（客戶端提供改變的屬性）约计。
DELETE（DELETE）：從服務(wù)器刪除資源。
下面是一些簡單的例子：
GET /zoos：列出所有動(dòng)物園
POST /zoos：新建一個(gè)動(dòng)物園
GET /zoos/ID：獲取某個(gè)指定動(dòng)物園的信息
PUT /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的全部信息）
PATCH /zoos/ID：更新某個(gè)指定動(dòng)物園的信息（提供該動(dòng)物園的部分信息）
DELETE /zoos/ID：刪除某個(gè)動(dòng)物園
GET /zoos/ID/animals：列出某個(gè)指定動(dòng)物園的所有動(dòng)物
DELETE /zoos/ID/animals/ID：刪除某個(gè)指定動(dòng)物園的指定動(dòng)物
六迁筛、過濾信息
如果記錄數(shù)量很多煤蚌，服務(wù)器不可能都將它們返回給用戶。API應(yīng)該提供參數(shù)细卧，過濾返回結(jié)果尉桩，下面是一些常見的參數(shù)：
?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁贪庙，以及每頁的記錄數(shù)蜘犁。
?sortby=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序，以及排序順序止邮。
?animal_type_id=1：指定篩選條件
參數(shù)的設(shè)計(jì)允許存在冗余这橙，即允許API路徑和URL參數(shù)偶爾有重復(fù)。比如导披，GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的屈扎。
七、狀態(tài)碼
服務(wù)器向用戶返回的狀態(tài)碼和提示信息撩匕，常見的有以下一些（方括號(hào)中是該狀態(tài)碼對(duì)應(yīng)的HTTP動(dòng)詞）：
200 OK - [GET]：服務(wù)器成功返回用戶請求的數(shù)據(jù)鹰晨，該操作是冪等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數(shù)據(jù)成功止毕。
202 Accepted - [*]：表示一個(gè)請求已經(jīng)進(jìn)入后臺(tái)排隊(duì)（異步任務(wù)）
204 NO CONTENT - [DELETE]：用戶刪除數(shù)據(jù)成功模蜡。
400 INVALID REQUEST - [POST/PUT/PATCH]：用戶發(fā)出的請求有錯(cuò)誤，服務(wù)器沒有進(jìn)行新建或修改數(shù)據(jù)的操作扁凛，該操作是冪等的忍疾。
401 Unauthorized - [*]：表示用戶沒有權(quán)限（令牌、用戶名谨朝、密碼錯(cuò)誤）膝昆。
403 Forbidden - [*] 表示用戶得到授權(quán)（與401錯(cuò)誤相對(duì)）丸边，但是訪問是被禁止的叠必。
404 NOT FOUND - [*]：用戶發(fā)出的請求針對(duì)的是不存在的記錄荚孵，服務(wù)器沒有進(jìn)行操作，該操作是冪等的纬朝。
406 Not Acceptable - [GET]：用戶請求的格式不可得（比如用戶請求JSON格式收叶，但是只有XML格式）。
410 Gone -[GET]：用戶請求的資源被永久刪除共苛，且不會(huì)再得到的判没。
422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個(gè)對(duì)象時(shí)，發(fā)生一個(gè)驗(yàn)證錯(cuò)誤隅茎。
500 INTERNAL SERVER ERROR - [*]：服務(wù)器發(fā)生錯(cuò)誤澄峰，用戶將無法判斷發(fā)出的請求是否成功。
詳細(xì)的狀態(tài)碼列表可見這里辟犀。
八俏竞、錯(cuò)誤處理
如果狀態(tài)碼是4xx，就應(yīng)該向用戶返回出錯(cuò)信息堂竟。一般來說魂毁，返回的信息中將error作為鍵名，出錯(cuò)信息作為鍵值即可出嘹。
例如：
{
error: "Invalid API key"
}
九席楚、返回結(jié)果
針對(duì)不同操作，服務(wù)器向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范：
GET /collection：返回資源對(duì)象的列表（數(shù)組）
GET /collection/resource：返回單個(gè)資源對(duì)象
POST /collection：返回新生成的資源對(duì)象
PUT /collection/resource：返回完整的資源對(duì)象
PATCH /collection/resource：返回完整的資源對(duì)象
DELETE /collection/resource：返回一個(gè)空文檔
本文來自 qq_31805915 的CSDN 博客 税稼，全文地址請點(diǎn)擊：https://blog.csdn.net/qq_31805915/article/details/79951929?utm_source=copy
整體規(guī)范建議采用RESTful 方式來實(shí)施烦秩。
協(xié)議
API與用戶的通信協(xié)議，總是使用HTTPs協(xié)議郎仆，確保交互數(shù)據(jù)的傳輸安全只祠。
域名
應(yīng)該盡量將API部署在專用域名之下。
https://api.example.com
如果確定API很簡單丸升，不會(huì)有進(jìn)一步擴(kuò)展铆农，可以考慮放在主域名下。
https://example.org/api/
api版本控制
應(yīng)該將API的版本號(hào)放入U(xiǎn)RL狡耻。
https://api.example.com/v{n}/
另一種做法是墩剖，將版本號(hào)放在HTTP頭信息中，但不如放入U(xiǎn)RL方便和直觀夷狰。Github采用這種做法岭皂。
采用多版本并存，增量發(fā)布的方式
v{n} n代表版本號(hào),分為整形和浮點(diǎn)型
整形的版本號(hào): 大功能版本發(fā)布形式沼头；具有當(dāng)前版本狀態(tài)下的所有API接口 ,例如：v1,v2
浮點(diǎn)型：為小版本號(hào)爷绘，只具備補(bǔ)充api的功能书劝，其他api都默認(rèn)調(diào)用對(duì)應(yīng)大版本號(hào)的api 例如：v1.1 v2.2
API 路徑規(guī)則
路徑又稱"終點(diǎn)"（endpoint），表示API的具體網(wǎng)址土至。
在RESTful架構(gòu)中购对，每個(gè)網(wǎng)址代表一種資源（resource），所以網(wǎng)址中不能有動(dòng)詞陶因，只能有名詞骡苞，而且所用的名詞往往與數(shù)據(jù)庫的表格名對(duì)應(yīng)。一般來說楷扬，數(shù)據(jù)庫中的表都是同種記錄的"集合"（collection）解幽，所以API中的名詞也應(yīng)該使用復(fù)數(shù)死陆。
舉例來說狱意，有一個(gè)API提供動(dòng)物園（zoo）的信息，還包括各種動(dòng)物和雇員的信息涤姊，則它的路徑應(yīng)該設(shè)計(jì)成下面這樣镣衡。
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
HTTP請求方式
對(duì)于資源的具體操作類型霜定，由HTTP動(dòng)詞表示。
常用的HTTP動(dòng)詞有下面四個(gè)（括號(hào)里是對(duì)應(yīng)的SQL命令）捆探。
GET（SELECT）：從服務(wù)器取出資源（一項(xiàng)或多項(xiàng)）然爆。
POST（CREATE）：在服務(wù)器新建一個(gè)資源。
PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）黍图。
DELETE（DELETE）：從服務(wù)器刪除資源曾雕。
下面是一些例子。
GET /product：列出所有商品
POST /product：新建一個(gè)商品
GET /product/ID：獲取某個(gè)指定商品的信息
PUT /product/ID：更新某個(gè)指定商品的信息
DELETE /product/ID：刪除某個(gè)商品
GET /product/ID/purchase ：列出某個(gè)指定商品的所有投資者
get /product/ID/purchase/ID：獲取某個(gè)指定商品的指定投資者信息
過濾信息
如果記錄數(shù)量很多助被，服務(wù)器不可能都將它們返回給用戶剖张。API應(yīng)該提供參數(shù)，過濾返回結(jié)果揩环。
下面是一些常見的參數(shù)搔弄。
?limit=10：指定返回記錄的數(shù)量
?offset=10：指定返回記錄的開始位置。
?page=2&per_page=100：指定第幾頁丰滑，以及每頁的記錄數(shù)顾犹。
?sortby=name&order=asc：指定返回結(jié)果按照哪個(gè)屬性排序，以及排序順序褒墨。
?producy_type=1：指定篩選條件
API 傳入?yún)?shù)
參入?yún)?shù)分為4種類型：
地址欄參數(shù)
- restful 地址欄參數(shù) /api/v1/product/122 122為產(chǎn)品編號(hào)炫刷，獲取產(chǎn)品為122的信息
- get方式的查詢字串 見過濾信息小節(jié)
請求body數(shù)據(jù)
cookie
request header
cookie和header 一般都是用于OAuth認(rèn)證的2種途徑
返回?cái)?shù)據(jù)
只要api接口成功接到請求，就不能返回200以外的HTTP狀態(tài)郁妈。
為了保障前后端的數(shù)據(jù)交互的順暢浑玛，建議規(guī)范數(shù)據(jù)的返回，并采用固定的數(shù)據(jù)格式封裝噩咪。
接口返回模板：
{
status:0,
data:{}||[],
msg:’’
}
status: 接口的執(zhí)行的狀態(tài)
=0表示成功
<0 表示有異常=""
Data 接口的主數(shù)據(jù)
顾彰，可以根據(jù)實(shí)際返回?cái)?shù)組或JSON對(duì)象
Msg
當(dāng)status!=0 都應(yīng)該有錯(cuò)誤信息
非Restful Api的需求
由于實(shí)際業(yè)務(wù)開展過程中极阅，可能會(huì)出現(xiàn)各種的api不是簡單的restful 規(guī)范能實(shí)現(xiàn)的，因此涨享，需要有一些api突破restful規(guī)范原則筋搏。特別是移動(dòng)互聯(lián)網(wǎng)的api設(shè)計(jì)，更需要有一些特定的api來優(yōu)化數(shù)據(jù)請求的交互灰伟。
頁面級(jí)的api
把當(dāng)前頁面中需要用到的所有數(shù)據(jù)通過一個(gè)接口一次性返回全部數(shù)據(jù)
舉例
api/v1/get-home-data 返回首頁用到的所有數(shù)據(jù)
這類API有一個(gè)非常不好的地址拆又，只要業(yè)務(wù)需求變動(dòng)，這個(gè)api就需要跟著變更栏账。
自定義組合api
把當(dāng)前用戶需要在第一時(shí)間內(nèi)容加載的多個(gè)接口合并成一個(gè)請求發(fā)送到服務(wù)端，服務(wù)端根據(jù)請求內(nèi)容栈源，一次性把所有數(shù)據(jù)合并返回,相比于頁面級(jí)api挡爵，具備更高的靈活性，同時(shí)又能很容易的實(shí)現(xiàn)頁面級(jí)的api功能甚垦。
規(guī)范
地址：api/v1/batApi
傳入?yún)?shù)：
data:[
{url:'api1',type:'get',data:{...}},
{url:'api2',type:'get',data:{...}},
{url:'api3',type:'get',data:{...}},
{url:'api4',type:'get',data:{...}}
]返回?cái)?shù)據(jù)
{status:0,msg:'',
data:[
{status:0,msg:'',data:[]},
{status:-1,msg:'',data:{}},
{status:1,msg:'',data:{}},
{status:0,msg:'',data:[]},
]
}
Api共建平臺(tái)
RAP是一個(gè)GUI的WEB接口管理工具茶鹃。在RAP中，您可定義接口的URL艰亮、請求&響應(yīng)細(xì)節(jié)格式等等闭翩。通過分析這些數(shù)據(jù)，RAP提供MOCK服務(wù)迄埃、測試服務(wù)等自動(dòng)化工具疗韵。RAP同時(shí)提供大量企業(yè)級(jí)功能，幫助企業(yè)和團(tuán)隊(duì)高效的工作侄非。
什么是RAP?
在前后端分離的開發(fā)模式下蕉汪，我們通常需要定義一份接口文檔來規(guī)范接口的具體信息。如一個(gè)請求的地址逞怨、有幾個(gè)參數(shù)者疤、參數(shù)名稱及類型含義等等。RAP 首先方便團(tuán)隊(duì)錄入叠赦、查看和管理這些接口文檔驹马，并通過分析結(jié)構(gòu)化的文檔數(shù)據(jù)，重復(fù)利用并生成自測數(shù)據(jù)除秀、提供自測控制臺(tái)等等... 大幅度提升開發(fā)效率糯累。
RAP的特色
強(qiáng)大的GUI工具 給力的用戶體驗(yàn)，你將會(huì)愛上使用RAP來管理您的API文檔鳞仙。
完善的MOCK服務(wù) 文檔定義好的瞬間寇蚊，所有接口已經(jīng)準(zhǔn)備就緒。有了MockJS棍好，無論您的業(yè)務(wù)模型有多復(fù)雜仗岸，它都能很好的滿足允耿。
龐大的用戶群 RAP在阿里巴巴有200多個(gè)大型項(xiàng)目在使用，也有許多著名的公司扒怖、開源人士在使用较锡。RAP跟隨這些業(yè)務(wù)的成行而成長，專注細(xì)節(jié)盗痒，把握質(zhì)量蚂蕴，經(jīng)得住考驗(yàn)。
免費(fèi) + 專業(yè)的技術(shù)支持 RAP是免費(fèi)的俯邓，而且你的技術(shù)咨詢都將在24小時(shí)內(nèi)得到答復(fù)骡楼。大多數(shù)情況，在1小時(shí)內(nèi)會(huì)得到答復(fù)稽鞭。
RAP是一個(gè)可視化接口管理工具 通過分析接口結(jié)構(gòu)鸟整，動(dòng)態(tài)生成模擬數(shù)據(jù)，校驗(yàn)真實(shí)接口正確性朦蕴， 圍繞接口定義篮条，通過一系列自動(dòng)化工具提升我們的協(xié)作效率。我們的口號(hào)：提高效率吩抓，回家吃晚飯涉茧！
