APP開(kāi)發(fā)規(guī)范—APP接口開(kāi)發(fā)規(guī)范文檔-V1.0[17頁(yè)]

1、封 面作者：ZHANGJIAN 僅供個(gè)人學(xué)習(xí)，勿做商業(yè)用途 北京天晴APP接口規(guī)范文檔 手機(jī)客戶端接口文檔 文件狀態(tài)： 草稿 正式發(fā)布 正在修改文件標(biāo)識(shí)：當(dāng)前版本：1.0作 者：北京天晴 完成日期：版 本 歷 史版本/狀態(tài)作者參與者起止日期備注V1.0/草稿韓磊移動(dòng)小組目錄一、概述1文檔來(lái)自于網(wǎng)絡(luò)搜索1.1 有關(guān)接口1文檔來(lái)自于網(wǎng)絡(luò)搜索1.1.1接口是純數(shù)據(jù)的交互1文檔來(lái)自于網(wǎng)絡(luò)搜索1.2 接口的分類1文檔來(lái)自于網(wǎng)絡(luò)搜索1.2.1查詢類接口1文檔來(lái)自于網(wǎng)絡(luò)搜索1.2.2 操作類接口1文檔來(lái)自于網(wǎng)絡(luò)搜索1.2.3上傳下載類接口1文檔來(lái)自于網(wǎng)絡(luò)搜索1.2.4推送類接口1文檔來(lái)自于網(wǎng)絡(luò)搜索二、查詢類

2、接口格式規(guī)范1文檔來(lái)自于網(wǎng)絡(luò)搜索2.1獲取單條對(duì)象信息1文檔來(lái)自于網(wǎng)絡(luò)搜索2.1.1 請(qǐng)求格式1文檔來(lái)自于網(wǎng)絡(luò)搜索2.1.2參數(shù)說(shuō)明2文檔來(lái)自于網(wǎng)絡(luò)搜索2.1.3正常返回結(jié)果2文檔來(lái)自于網(wǎng)絡(luò)搜索2.2獲取列表對(duì)象信息2文檔來(lái)自于網(wǎng)絡(luò)搜索2.2.1 請(qǐng)求格式2文檔來(lái)自于網(wǎng)絡(luò)搜索2.2.2參數(shù)說(shuō)明3文檔來(lái)自于網(wǎng)絡(luò)搜索2.2.3正常返回結(jié)果3文檔來(lái)自于網(wǎng)絡(luò)搜索三、操作類接口4文檔來(lái)自于網(wǎng)絡(luò)搜索3.1 新增操作4文檔來(lái)自于網(wǎng)絡(luò)搜索3.1.1接口說(shuō)明4文檔來(lái)自于網(wǎng)絡(luò)搜索3.1.2參數(shù)說(shuō)明4文檔來(lái)自于網(wǎng)絡(luò)搜索3.1.3正常返回結(jié)果4文檔來(lái)自于網(wǎng)絡(luò)搜索3.1.4錯(cuò)誤返回列表4文檔來(lái)自于網(wǎng)絡(luò)搜索3.2 修改操

3、作5文檔來(lái)自于網(wǎng)絡(luò)搜索3.2.1接口說(shuō)明5文檔來(lái)自于網(wǎng)絡(luò)搜索3.2.2參數(shù)說(shuō)明5文檔來(lái)自于網(wǎng)絡(luò)搜索3.2.3正常返回結(jié)果5文檔來(lái)自于網(wǎng)絡(luò)搜索3.2.4錯(cuò)誤返回列表5文檔來(lái)自于網(wǎng)絡(luò)搜索3.3 刪除操作5文檔來(lái)自于網(wǎng)絡(luò)搜索3.3.1接口說(shuō)明5文檔來(lái)自于網(wǎng)絡(luò)搜索3.3.2參數(shù)說(shuō)明6文檔來(lái)自于網(wǎng)絡(luò)搜索3.3.3正常返回結(jié)果6文檔來(lái)自于網(wǎng)絡(luò)搜索3.3.4錯(cuò)誤返回列表6文檔來(lái)自于網(wǎng)絡(luò)搜索四、上傳下載類6文檔來(lái)自于網(wǎng)絡(luò)搜索4.1 上傳文件6文檔來(lái)自于網(wǎng)絡(luò)搜索4.1.1接口說(shuō)明6文檔來(lái)自于網(wǎng)絡(luò)搜索4.1.2參數(shù)說(shuō)明7文檔來(lái)自于網(wǎng)絡(luò)搜索4.1.3正常返回結(jié)果7文檔來(lái)自于網(wǎng)絡(luò)搜索4.1.4錯(cuò)誤返回列表7文檔來(lái)自于

4、網(wǎng)絡(luò)搜索4.2 下載文件7文檔來(lái)自于網(wǎng)絡(luò)搜索4.2.1接口說(shuō)明7文檔來(lái)自于網(wǎng)絡(luò)搜索4.2.2參數(shù)說(shuō)明7文檔來(lái)自于網(wǎng)絡(luò)搜索4.2.3正常返回結(jié)果8文檔來(lái)自于網(wǎng)絡(luò)搜索4.2.4錯(cuò)誤返回列表8文檔來(lái)自于網(wǎng)絡(luò)搜索五、推送類接口8文檔來(lái)自于網(wǎng)絡(luò)搜索5.1 推送消息8文檔來(lái)自于網(wǎng)絡(luò)搜索5.1.1接口說(shuō)明8文檔來(lái)自于網(wǎng)絡(luò)搜索5.1.2參數(shù)說(shuō)明8文檔來(lái)自于網(wǎng)絡(luò)搜索5.1.3正常返回結(jié)果8文檔來(lái)自于網(wǎng)絡(luò)搜索5.1.4錯(cuò)誤返回列表8文檔來(lái)自于網(wǎng)絡(luò)搜索六、通用返回格式9文檔來(lái)自于網(wǎng)絡(luò)搜索6.1 正確返回9文檔來(lái)自于網(wǎng)絡(luò)搜索6.1.1接口說(shuō)明9文檔來(lái)自于網(wǎng)絡(luò)搜索6.1.2參數(shù)說(shuō)明9文檔來(lái)自于網(wǎng)絡(luò)搜索6.1.3正常返回

5、結(jié)果9文檔來(lái)自于網(wǎng)絡(luò)搜索6.1.4錯(cuò)誤返回列表9文檔來(lái)自于網(wǎng)絡(luò)搜索6.2 錯(cuò)誤返回9文檔來(lái)自于網(wǎng)絡(luò)搜索6.2.1接口說(shuō)明9文檔來(lái)自于網(wǎng)絡(luò)搜索6.2.2參數(shù)說(shuō)明10文檔來(lái)自于網(wǎng)絡(luò)搜索6.2.3正常返回結(jié)果10文檔來(lái)自于網(wǎng)絡(luò)搜索6.2.4錯(cuò)誤返回列表10文檔來(lái)自于網(wǎng)絡(luò)搜索七、附錄10文檔來(lái)自于網(wǎng)絡(luò)搜索7.1 通用錯(cuò)誤返回列表10文檔來(lái)自于網(wǎng)絡(luò)搜索7.2 URL地址信息11文檔來(lái)自于網(wǎng)絡(luò)搜索7.2.1 主機(jī)地址11文檔來(lái)自于網(wǎng)絡(luò)搜索7.2.2 URL列表11文檔來(lái)自于網(wǎng)絡(luò)搜索7.3 安全機(jī)制11文檔來(lái)自于網(wǎng)絡(luò)搜索7.3.1 驗(yàn)證簽名機(jī)制11文檔來(lái)自于網(wǎng)絡(luò)搜索7.4 其他11文檔來(lái)自于網(wǎng)絡(luò)搜索7.2.

6、1 列表數(shù)據(jù)為空的返回11文檔來(lái)自于網(wǎng)絡(luò)搜索5 / 18個(gè)人收集整理 勿做商業(yè)用途一、概述1.1 有關(guān)接口1.1.1接口是純數(shù)據(jù)的交互APP接口是移動(dòng)設(shè)備和業(yè)務(wù)之間進(jìn)行通信的途徑。實(shí)質(zhì)就是以特定的規(guī)則通過(guò)接口直接操作數(shù)據(jù)庫(kù)的增刪改查。1.2 接口的分類1.2.1查詢類接口查詢類接口是指客戶端傳遞一些參數(shù)，服務(wù)端根據(jù)參數(shù)依據(jù)需求，前往數(shù)據(jù)庫(kù)查詢需要的結(jié)果返回?cái)?shù)據(jù)的一類接口。文檔來(lái)自于網(wǎng)絡(luò)搜索返回類型一般有兩種。第一種是返回一個(gè)對(duì)象，第二種是返回一個(gè)數(shù)組對(duì)象。第一種比如登陸，客戶端把用戶名密碼上傳到接口，服務(wù)器返回用戶的個(gè)人信息。第二種比如獲取客戶，客戶端把用戶的身份信息上傳到接口，服務(wù)器返回此身

7、份下的所有客戶數(shù)組集合。1.2.2 操作類接口操作類接口是指，客戶端通過(guò)接口進(jìn)行一些增刪改的操作。比如新增一個(gè)客戶，修改客戶信息，或者刪除一個(gè)客戶。服務(wù)器一般返回執(zhí)行的狀態(tài)，有的需要返回執(zhí)行結(jié)果的一些信息，比如新增客戶后，返回客戶的ID。文檔來(lái)自于網(wǎng)絡(luò)搜索1.2.3上傳下載類接口上傳下載類接口是涉及到文件傳輸?shù)慕涌凇１热缟蟼黝^像，需要上傳圖片到服務(wù)器，服務(wù)端根據(jù)需求響應(yīng)保存并返回結(jié)果。比如客戶端需要顯示用戶頭像，需要讀取網(wǎng)絡(luò)圖片文件，在手機(jī)上進(jìn)行顯示。文檔來(lái)自于網(wǎng)絡(luò)搜索1.2.4推送類接口除了客戶端主動(dòng)去請(qǐng)求服務(wù)端，獲取需要信息之外。有時(shí)候，也存在服務(wù)端有消息需要通知客戶端的情況，這時(shí)候就是服

8、務(wù)端向客戶端發(fā)送消息。這類需求可以通過(guò)客戶端短時(shí)間類循環(huán)請(qǐng)求解決，也可以通過(guò)第三方專業(yè)推送解決。也可以通過(guò)自己使用socket或者xmpp等協(xié)議進(jìn)行開(kāi)發(fā)。文檔來(lái)自于網(wǎng)絡(luò)搜索二、查詢類接口格式規(guī)范2.1獲取單條對(duì)象信息2.1.1 請(qǐng)求格式URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制2.1.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明xxxtrueString用戶名2.1.3正常返回結(jié)果返回鍵類型返回值說(shuō)明resultString結(jié)果代碼信號(hào)ok 結(jié)果成功， fail結(jié)果失敗ResponseObject響應(yīng)體Key1int 響應(yīng)字段值 Key2 String 響應(yīng)字段值 Key3 O

9、bject 響應(yīng)字段值可以依然包含對(duì)象體 Key3_Key1 int 響應(yīng)字段值 result:ok , Response: userName: Mary, sex: 1, Address: city: JiNan , county: LiXia 2.1.4錯(cuò)誤返回列表詳見(jiàn)：通用錯(cuò)誤返回列表2.2獲取列表對(duì)象信息2.2.1 請(qǐng)求格式URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制2.2.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明xxxtrueString用戶名Pagefalseint第幾頁(yè)，不傳遞默認(rèn)第一頁(yè)Sizefalseint一頁(yè)多少條，不傳遞默認(rèn)20條2.2.3正常返回結(jié)果返

10、回鍵類型返回值說(shuō)明resultString結(jié)果代碼信號(hào)ResponseObject響應(yīng)體LastUpdateTimeString 最后一條更新時(shí)間根據(jù)此時(shí)間判斷新舊 ThisPageNumber int 當(dāng)前頁(yè)條數(shù)判斷是否為空，是否有下頁(yè) DataList ArrayObject 對(duì)象列表時(shí)間倒序排列 “result”:”ok” , Response: LastUpdateTime: 2012-12-11 22:01:09, ThisPageNumber: 2, DataList: id: 1, date: 2014-07-24, detail: points: 50

11、 , id: 2, date: 2014-07-24, detail: points: 50 2.2.4錯(cuò)誤返回列表詳見(jiàn)：通用錯(cuò)誤返回列表三、操作類接口3.1 新增操作3.1.1接口說(shuō)明URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制3.1.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明xxxtrueString用戶名xxxtrueStringxxxtrueStringxxxtrueString3.1.3正常返回結(jié)果返回鍵類型返回值說(shuō)明resultString結(jié)果代碼信號(hào)ResponseObject響應(yīng)體 idint增數(shù)據(jù)的ID或者標(biāo)志 text String

12、 操作提示語(yǔ)如添加客戶成功，可為空 “result”:”ok” , Response: id: 1, text: 3.1.4錯(cuò)誤返回列表詳見(jiàn)：通用錯(cuò)誤返回列表3.2 修改操作3.2.1接口說(shuō)明URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制3.2.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明xxxtrueString用戶名xxxtrueStringxxxtrueStringxxxtrueString3.2.3正常返回結(jié)果返回鍵類型返回值說(shuō)明resultString結(jié)果代碼信號(hào)ResponseObject響應(yīng)體 idint數(shù)據(jù)的ID或者標(biāo)志 text String 操作提示語(yǔ)如修改客戶

13、成功，可為空 “result”:”ok” , Response: id: 1, text: 3.2.4錯(cuò)誤返回列表詳見(jiàn)：通用錯(cuò)誤返回列表3.3 刪除操作3.3.1接口說(shuō)明URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制3.3.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明xxxtrueString用戶名xxxtrueString3.3.3正常返回結(jié)果返回鍵類型返回值說(shuō)明resultString結(jié)果代碼信號(hào)ResponseObject響應(yīng)體 idint數(shù)據(jù)的ID或者標(biāo)志 text String 操作提示語(yǔ)如刪除客戶成功，可為空 “result”:”ok” , Response: id:

14、1, text: 親，刪除客戶成功 3.3.4錯(cuò)誤返回列表詳見(jiàn)：通用錯(cuò)誤返回列表四、上傳下載類4.1 上傳文件4.1.1接口說(shuō)明URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制4.1.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明xxxtrueString用戶名xxxtrueFile值為文件類型，處理同Web中的表單FILE一樣4.1.3正常返回結(jié)果返回鍵類型返回值說(shuō)明resultString結(jié)果代碼信號(hào)ResponseObject響應(yīng)體 filePathString文件存放的絕對(duì)路徑上傳 “result”:”ok” , Response: filePath: 4.1.4錯(cuò)誤返回列表詳

15、見(jiàn)：通用錯(cuò)誤返回列表4.2 下載文件4.2.1接口說(shuō)明URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制4.2.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明xxxtrueString文件網(wǎng)絡(luò)絕對(duì)路徑4.2.3正常返回結(jié)果返回鍵類型返回值說(shuō)明確保文件可以正常訪問(wèn)下載4.2.4錯(cuò)誤返回列表詳見(jiàn)：通用錯(cuò)誤返回列表五、推送類接口5.1 推送消息5.1.1接口說(shuō)明URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制5.1.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明5.1.3正常返回結(jié)果返回鍵類型返回值說(shuō)明5.1.4錯(cuò)誤返回列表詳見(jiàn)：通用錯(cuò)誤返回列表六、通用返回格式6.1 正確返回6.1.

16、1接口說(shuō)明URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制6.1.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明xxxtrueString用戶名6.1.3正常返回結(jié)果返回鍵類型返回值說(shuō)明resultString結(jié)果代碼信號(hào)ResponseObject響應(yīng)體 “result”:”ok” ,Response: 6.1.4錯(cuò)誤返回列表詳見(jiàn)：通用錯(cuò)誤返回列表6.2 錯(cuò)誤返回6.2.1接口說(shuō)明URL支持格式JOSNHTTP請(qǐng)求方式POST是否登錄驗(yàn)證請(qǐng)求數(shù)限制6.2.2參數(shù)說(shuō)明參數(shù)名必選類型及范圍說(shuō)明xxxtrueString用戶名6.2.3正常返回結(jié)果返回鍵類型返回值說(shuō)明resultStrin

17、g結(jié)果代碼信號(hào)ResponseObject響應(yīng)體errorTextString錯(cuò)誤信息 result:fail ,Response: errorCode: -998 , errorText: 用戶名密碼錯(cuò)誤 6.2.4錯(cuò)誤返回列表詳見(jiàn)：通用錯(cuò)誤返回列表七、附錄7.1 通用錯(cuò)誤返回列表errorCode表示說(shuō)明-999通用錯(cuò)誤只用于一處，或者無(wú)關(guān)緊要的提示性，錯(cuò)誤-998用戶名密碼錯(cuò)誤-997用戶登陸超時(shí)或別處登錄7.2 URL地址信息7.2.1 主機(jī)地址LocalHost正式地址：/LocalHost測(cè)試地址：/7.2.2 U

18、RL列表URL描述備注API/login用戶登錄無(wú)需驗(yàn)證7.3 安全機(jī)制7.3.1 驗(yàn)證簽名機(jī)制生成Token7.4 其他7.2.1 列表數(shù)據(jù)為空的返回列表數(shù)據(jù)為空時(shí)顯示 DataList: 版權(quán)申明本文部分內(nèi)容，包括文字、圖片、以及設(shè)計(jì)等在網(wǎng)上搜集整理。版權(quán)為張儉個(gè)人所有This article includes some parts, including text, pictures, and design. Copyright is Zhang Jians personal ownership.文檔來(lái)自于網(wǎng)絡(luò)搜索用戶可將本文的內(nèi)容或服務(wù)用于個(gè)人學(xué)習(xí)、研究或欣賞，以及其他非商業(yè)性或非盈利性

19、用途，但同時(shí)應(yīng)遵守著作權(quán)法及其他相關(guān)法律的規(guī)定，不得侵犯本網(wǎng)站及相關(guān)權(quán)利人的合法權(quán)利。除此以外，將本文任何內(nèi)容或服務(wù)用于其他用途時(shí)，須征得本人及相關(guān)權(quán)利人的書(shū)面許可，并支付報(bào)酬。文檔來(lái)自于網(wǎng)絡(luò)搜索Users may use the contents or services of this article for personal study, research or appreciation, and other non-commercial or non-profit purposes, but at the same time, they shall abide by the provisions of copyright law and other relevant laws, and shall not infringe upon the legitimate