APP開發(fā)規(guī)范—APP接口開發(fā)規(guī)范文檔-V017

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

2、于網(wǎng)絡(luò)搜索 1.2.3 上傳下載類接口 6文檔來自于網(wǎng)絡(luò)搜索 1.2.4 推送類接口 6文檔來自于網(wǎng)絡(luò)搜索 二、查詢類接口格式規(guī)范 6文檔來自于網(wǎng)絡(luò)搜索 2.1 獲取單條對象信息 6文檔來自于網(wǎng)絡(luò)搜索 2.1.1 請求格式 6文檔來自于網(wǎng)絡(luò)搜索 2.1.2 參數(shù)說明 7文檔來自于網(wǎng)絡(luò)搜索 2.1.3 正常返回結(jié)果 7文檔來自于網(wǎng)絡(luò)搜索 2.2 獲取列表對象信息 7文檔來自于網(wǎng)絡(luò)搜索 2.2.1 請求格式 7文檔來自于網(wǎng)絡(luò)搜索 2.2.2 參數(shù)說明 8文檔來自于網(wǎng)絡(luò)搜索 2.2.3 正常返回結(jié)果 8文檔來自于網(wǎng)絡(luò)搜索 三、操作類接口 9文檔來自于網(wǎng)絡(luò)搜索 3.1 新增操作 9文檔來自于網(wǎng)絡(luò)搜索

3、3.1.1 接口說明 9文檔來自于網(wǎng)絡(luò)搜索 3.1.2 參數(shù)說明 9文檔來自于網(wǎng)絡(luò)搜索 3.1.3正常返回結(jié)果 9文檔來自于網(wǎng)絡(luò)搜索 3.1.4 錯誤返回列表 9文檔來自于網(wǎng)絡(luò)搜索 3.2 修改操作 9文檔來自于網(wǎng)絡(luò)搜索 3.2.1 接口說明 9文檔來自于網(wǎng)絡(luò)搜索 3.2.2 參數(shù)說明 10文檔來自于網(wǎng)絡(luò)搜索 3.2.3 正常返回結(jié)果 10文檔來自于網(wǎng)絡(luò)搜索 3.2.4 錯誤返回列表 10文檔來自于網(wǎng)絡(luò)搜索 3.3 刪除操作 10文檔來自于網(wǎng)絡(luò)搜索 3.3.1 接口說明 10文檔來自于網(wǎng)絡(luò)搜索 3.3.2 參數(shù)說明 10文檔來自于網(wǎng)絡(luò)搜索 3.3.3 正常返回結(jié)果 10文檔來自于網(wǎng)絡(luò)搜索 3.

4、3.4 錯誤返回列表 11 文檔來自于網(wǎng)絡(luò)搜索 四、上傳下載類 11 文檔來自于網(wǎng)絡(luò)搜索 4.1 上傳文件 11 文檔來自于網(wǎng)絡(luò)搜索 4.1.1 接口說明 11 文檔來自于網(wǎng)絡(luò)搜索 4.1.2 參數(shù)說明 11 文檔來自于網(wǎng)絡(luò)搜索 4.1.3 正常返回結(jié)果 11 文檔來自于網(wǎng)絡(luò)搜索 4.1.4 錯誤返回列表 12文檔來自于網(wǎng)絡(luò)搜索 4.2 下載文件 12文檔來自于網(wǎng)絡(luò)搜索 4.2.1 接口說明 12文檔來自于網(wǎng)絡(luò)搜索 4.2.2 參數(shù)說明 12文檔來自于網(wǎng)絡(luò)搜索 4 / 17 4.2.3 正常返回結(jié)果 12文檔來自于網(wǎng)絡(luò)搜索 4.2.4 錯誤返回列表 12文檔來自于網(wǎng)絡(luò)搜索 五、推送類接口 12

5、文檔來自于網(wǎng)絡(luò)搜索 5.1 推送消息 12文檔來自于網(wǎng)絡(luò)搜索 5.1.1 接口說明 12文檔來自于網(wǎng)絡(luò)搜索 5.1.2 參數(shù)說明 13文檔來自于網(wǎng)絡(luò)搜索 5.1.3 正常返回結(jié)果 13文檔來自于網(wǎng)絡(luò)搜索 5.1.4 錯誤返回列表 13文檔來自于網(wǎng)絡(luò)搜索 六、通用返回格式 13文檔來自于網(wǎng)絡(luò)搜索 6.1 正確返回 13文檔來自于網(wǎng)絡(luò)搜索 6.1.1 接口說明 13文檔來自于網(wǎng)絡(luò)搜索 6.1.2 參數(shù)說明 13文檔來自于網(wǎng)絡(luò)搜索 6.1.3 正常返回結(jié)果 13文檔來自于網(wǎng)絡(luò)搜索 6.1.4 錯誤返回列表 14文檔來自于網(wǎng)絡(luò)搜索 6.2 錯誤返回 14文檔來自于網(wǎng)絡(luò)搜索 6.2.1 接口說明 14文

6、檔來自于網(wǎng)絡(luò)搜索 6.2.2 參數(shù)說明 14文檔來自于網(wǎng)絡(luò)搜索 6.2.3 正常返回結(jié)果 14文檔來自于網(wǎng)絡(luò)搜索 6.2.4 錯誤返回列表 14文檔來自于網(wǎng)絡(luò)搜索 七、附錄 15文檔來自于網(wǎng)絡(luò)搜索 7.1 通用錯誤返回列表 15文檔來自于網(wǎng)絡(luò)搜索 7.2 URL 地址信息 15文檔來自于網(wǎng)絡(luò)搜索 7.2.1 主機(jī)地址 15文檔來自于網(wǎng)絡(luò)搜索 7.2.2 URL 列表 15文檔來自于網(wǎng)絡(luò)搜索 7.3 安全機(jī)制 15文檔來自于網(wǎng)絡(luò)搜索 7.3.1 驗證簽名機(jī)制 15文檔來自于網(wǎng)絡(luò)搜索 7.4 其他 15文檔來自于網(wǎng)絡(luò)搜索 7.2.1 列表數(shù)據(jù)為空的返回 15文檔來自于網(wǎng)絡(luò)搜索 5 / 17 勿做商

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

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

9、 通知客戶端的情況， 這時候就是服務(wù)端向客戶端發(fā)送消息。 這類需求可以通過客戶端短時間 類循環(huán)請求解決，也可以通過第三方專業(yè)推送解決。也可以通過自己使用socket 或者 xmpp 等協(xié)議進(jìn)行開發(fā)。 文檔來自于網(wǎng)絡(luò)搜索 二、查詢類接口格式規(guī)范 2.1 獲取單條對象信息 2.1.1 請求格式 URL 支持格式 JOSN HTTP 請求方式 POST 是否登錄驗證 請求數(shù)限制 6 / 17 勿做商業(yè)用途 個人收集整理 2.1.2參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 xxx true String 用戶名 2.1.3正常返回結(jié)果 返回鍵 類型 返回值 說明 result String 結(jié)果代碼信

10、號 ok 結(jié)果成功， fail 結(jié)果失敗 Response Object 響應(yīng)體 Key1 int 響應(yīng)字段值 Key2 String 響應(yīng)字段值 Key3 Object 響應(yīng)字段值 可以依然包含對象體 Key3 Key1 int 響應(yīng)字段值 result:ok , Response: userName: Mary, sex: 1, Address: city: JiNan , county: LiXia 2.1.4錯誤返回列表 詳見：通用錯誤返回列表 2.2 獲取列表對象信息 2.2.1 請求格式 URL 支持格式 JOSN HTTP 請求方式 POST 是否登錄驗證 請求數(shù)限制 7 / 1

11、7 勿做商業(yè)用途 個人收集整理 2.2.2參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 xxx true String 用戶名 Page false int 第幾頁，不傳遞默認(rèn)第一頁 Size false int 一頁多少條，不傳遞默認(rèn) 20 條 2.2.3正常返回結(jié)果 返回鍵 類型 返回值 說明 result String 結(jié)果代碼信號 Response Object 響應(yīng)體 LastUpdateTime String 最后一條更新時間 根據(jù)此時間判斷新舊 ThisPageNumber int 當(dāng)前頁條數(shù) 判斷是否為空，是否有下頁 DataList ArrayObject 對象列表 時間倒序排列

12、 “ result ”: ”ok” , Response: LastUpdateTime: 2012-12-11 22:01:09, ThisPageNumber: 2, DataList: id: 1, date: 2014-07-24, detail: points: 50 , id: 2, date: 2014-07-24, detail: points: 50 2.2.4錯誤返回列表 詳見：通用錯誤返回列表 8 / 17 勿做商業(yè)用途 個人收集整理 三、操作類接口 3.1 新增操作 3.1.1接口說明 URL 支持格式 JOSN HT

13、TP 請求方式 POST 是否登錄驗證 請求數(shù)限制 3.1.2參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 xxx true String 用戶名 xxx true String xxx true String xxx true String 3.1.3正常返回結(jié)果 返回鍵 類型 返回值 說明 result String 結(jié)果代碼信號 Response Object 響應(yīng)體 id int 增數(shù)據(jù)的 ID 或者標(biāo)志 text String 操作提示語 如添加客戶成功，可為空 “ result ” : ” ok ” , Response: id: 1, text: 3.1.4錯誤返回列表 詳見：通用錯

14、誤返回列表 3.2 修改操作 3.2.1接口說明 URL 支持格式 JOSN HTTP 請求方式 POST 是否登錄驗證 請求數(shù)限制 9 / 17 勿做商業(yè)用途 個人收集整理 3.2.2參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 xxx true String 用戶名 xxx true String xxx true String xxx true String 3.2.3正常返回結(jié)果 返回鍵 類型 返回值 說明 result String 結(jié)果代碼信號 Response Object 響應(yīng)體 id int 數(shù)據(jù)的 ID 或者標(biāo)志 text String 操作提示語 如修改客戶成功，可為空 “

15、result ” : ” ok ” , Response: id: 1, text: 3.2.4錯誤返回列表 詳見：通用錯誤返回列表 3.3 刪除操作 3.3.1接口說明 URL 支持格式 JOSN HTTP 請求方式 POST 是否登錄驗證 請求數(shù)限制 3.3.2參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 xxx true String 用戶名 xxx true String 3.3.3正常返回結(jié)果 返回鍵 類型 返回值 說明 10 / 17 result String 結(jié)果代碼信號 Response Object 響應(yīng)體 id int 數(shù)據(jù)的 ID 或者標(biāo)志 text String 操作提示

16、語 如刪除客戶成功，可為空 “ result ” : ” ok ” , Response: id: 1, text: 親，刪除客戶成功 個人收集整理 勿做商業(yè)用途 3.3.4錯誤返回列表 詳見：通用錯誤返回列表 四、上傳下載類 4.1 上傳文件 4.1.1接口說明 URL 支持格式 JOSN HTTP 請求方式 POST 是否登錄驗證 請求數(shù)限制 4.1.2 參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 xxx true String 用戶名 xxx true File 值為文件類型，處理同 Web 中的表單 FILE 一樣 4.1.3正常返回結(jié)果 返回鍵 類型 返回值 說明 result Str

17、ing 結(jié)果代碼信號 Response Object 響應(yīng)體 filePath String 文件存放的絕對路徑 上傳 “ result ” : ” ok ” , Response: filePath: http:/ 11 / 17 勿做商業(yè)用途 個人收集整理 4.1.4錯誤返回列表 詳見：通用錯誤返回列表 4.2 下載文件 4.2.1接口說明 URL 支持格式 JOSN HTTP 請求方式 POST 是否登錄驗證 請求數(shù)限制 4.2.2 參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 xxx true String 文件網(wǎng)絡(luò)絕對路徑 4.2.3正常返回結(jié)果 返回鍵 類型 返回值 說明 確保文件可以

18、正常訪問下載 4.2.4錯誤返回列表 詳見：通用錯誤返回列表 五、推送類接口 5.1 推送消息 5.1.1接口說明 URL 支持格式 JOSN HTTP 請求方式 POST 是否登錄驗證 請求數(shù)限制 12 / 17 勿做商業(yè)用途 個人收集整理 5.1.2 參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 5.1.3正常返回結(jié)果 返回鍵 類型 返回值 說明 5.1.4錯誤返回列表 詳見：通用錯誤返回列表 六、通用返回格式 6.1 正確返回 6.1.1接口說明 URL 支持格式 JOSN HTTP 請求方式 POST 是否登錄驗證 請求數(shù)限制 6.1.2 參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 xxx

19、true String 用戶名 6.1.3正常返回結(jié)果 返回鍵 類型 返回值 說明 result String 結(jié)果代碼信號 Response Object 響應(yīng)體 13 / 17 勿做商業(yè)用途 個人收集整理 “ result ” : ” ok Response: 6.1.4錯誤返回列表 詳見：通用錯誤返回列表 6.2 錯誤返回 6.2.1接口說明 URL 支持格式 JOSN HTTP 請求方式 POST 是否登錄驗證 請求數(shù)限制 6.2.2參數(shù)說明 參數(shù)名 必選 類型及范圍 說明 xxx true String 用戶名 6.2.3正常返回結(jié)果 返回鍵 類型 返回值 說明 result Str

20、ing 結(jié)果代碼信號 Response Object 響應(yīng)體 errorText String 錯誤信息 result:fail , Response: errorCode: -998 , errorText: 用戶名密碼錯誤 6.2.4錯誤返回列表 詳見：通用錯誤返回列表 14 / 17 勿做商業(yè)用途 個人收集整理 七、附錄 7.1 通用錯誤返回列表 errorCode 表示 說明 -999 通用錯誤 只用于一處，或者無關(guān)緊要的提示性，錯誤 -998 用戶名密碼錯誤 -997 用戶登陸超時或別 處登錄 7.2 URL 地址信息 7.2.1 主機(jī)地址 LocalHost 正式地址： http:

21、// LocalHost 測試地址： / 7.2.2 URL 列表 URL 描述 備注 API/login 用戶登錄 無需驗證 7.3 安全機(jī)制 7.3.1 驗證簽名機(jī)制 生成 Token 7.4 其他 7.2.1 列表數(shù)據(jù)為空的返回 列表數(shù)據(jù)為空時顯示 DataList: 15 / 17 勿做商業(yè)用途 個人收集整理 版權(quán)申明 本文部分內(nèi)容，包括文字、圖片、以及設(shè)計等在網(wǎng)上搜集整理。 版權(quán)為張儉個人所有 This article includes some parts, including text, pictures, and desi

22、gn. Copyright is Zhang Jians personal ownership.文檔 來自于網(wǎng)絡(luò)搜索 用戶可將本文的內(nèi)容或服務(wù)用于個人學(xué)習(xí)、 研究或欣賞， 以及其 他非商業(yè)性或非盈利性用途， 但同時應(yīng)遵守著作權(quán)法及其他相關(guān)法律 的規(guī)定，不得侵犯本網(wǎng)站及相關(guān)權(quán)利人的合法權(quán)利。除此以外，將本 文任何內(nèi)容或服務(wù)用于其他用途時， 須征得本人及相關(guān)權(quán)利人的書面 許可，并支付報酬 。 文檔來自于網(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 copyrigh