Restful接口指导规则完整解读.doc

Restful接口设计规范一、 Restful简介REST是“REpresentational State Transfer”缩写，可以翻译成“体现状态转换”，但是在绝大多数场合中咱们只说REST或者RESTful。为什么会起这样一种奇怪名字呢？咱们可以从上述这篇论文中找到答案。Fielding在论文中将REST定位为“分布式超媒体应用（Distributed Hypermedia System）”架构风格，它在文中提到一种名为“HATEOAS（Hypermedia as the engine of application state）”概念。咱们运用一种面向最后顾客Web应用来对这个概念进行简朴阐述：这里所谓应用状态（Application State）表达Web应用客户端状态，简朴起见可以理解为会话状态。资源在浏览器中以超媒体形式呈现，通过点击超媒体中链接可以获取其他有关资源或者对当前资源进行相应解决，获取资源或者针对资源解决响应同样以超媒体形式再次呈当前浏览器上。由此可见，超媒体成为了驱动客户端会话状态转换引擎。借助于超媒体这种特殊资源呈现方式，应用状态转换体现为浏览器中呈现资源转换。如果将超媒体进一步抽象成普通意义上资源呈现（Representation ）方式，那么应用状态变成了可被呈现状态（REpresentational State）。应用状态之间转换就成了可被呈现状态装换（REpresentational State Transfer），这就是REST。二、 运管平台/烽行平台Restful接口原则1. 接口命名规则http:/ip:端口/v2/接口名IP：服务器IP地址端口：Restful端标语V2:版本号(2)接口名：命名规则：既有接口办法去第一种单词后，全小写命名，如：顾客余额信息实时查询能力，原接口名：queryBalanceRealSingle(String msisdn)Restful接口:http:/ip:端口/v2/balancerealsingle2. 参数规则参数提交方式：application/www-form-urlencoded参数命名：单词采用小写，复合词采用下划线分开全小写命名。参数规则：批量查询需有page_size以及page_num参数，避免一次性查询，某些参数需有默认值设定。附录：运管平台某些API规则顾客状态查询：服务地址： http:/ip:端口/v2/userstatusrealsingle提供顾客状态信息实时查询祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/userstatus?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1返回值：status ：0,message ：ok,result ：status:00 短信失败记录历史查询： 有LIST传递 待定服务地址： http:/ip:端口/v2/smsfaulthistory1返回短信失败记录相应数据祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式begin_time是无1010查询开始时间查询时间范畴：3个月内记录end_time是无1111查询结束时间查询时间范畴：3个月内记录page_size否1010返回记录数量，默以为10条记录，最大可设立为20条page_num否00、1、2分页页码，默以为0。 0代表第一页，1代表第二页，以此类推。 如果设立了此字段，则输出成果中具有total字段。示例：http:/ip:端口/v2/smsfaulthistory1?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1&begintime=1010&endtime=1111返回值：status ：0,message ：ok,result :顾客实时位置信息查询服务地址： http:/ip:端口/v2/locationinforealsingle返回顾客位置信息(经纬度)祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/locationinforealingles?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1返回值：status ：0,message ：ok,result ：lat:39.920411，lng：116.418224集团顾客数查询服务地址： http:/ip:端口/v2/locationinforealsingle返回该集团指定日期顾客总数祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密query_date是无1111所查询专网号码output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/locationinforealsingle?appid=100001&ebid=0001&query_date=1016&token=E4805d16520de693a3fe707cdc962045&msisdn=1返回值：status ：0,message ：ok,result ：totla:0流量池信息查询服务地址： http:/ip:端口/v2/gprspoolinfo查询集团流量池顾客数和大小祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密query_date是无1111所查询专网号码output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/gprspoolinfo?appid=100001&ebid=0001&transid=1001&query_date=1016&token=E4805d16520de693a3fe707cdc962045返回值：status ：0,message ：ok,result ：usersCount:10000,size:10240流量池使用量查询服务地址： http:/ip:端口/v2/gprspoolusedinfo查询集团流量池指定月份流量使用状况祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密query_date是无1111所查询专网号码output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/gprspoolusedinfo?appid=100001&ebid=0001&transid=1001&query_date=1016&token=E4805d16520de693a3fe707cdc962045返回值：status ：0,message ：ok,result ：gprsUserd:Balance:10000短信白名单管理服务地址： http:/ip:端口/v2/whitelist依照指定短信接入号和手机号列表进行短信白名单数据添加或删除 祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密opr_code是无01oprCode-操作类型 01 增长 02 删除serv_code是无短信接入号msisdn是无现网手机号output否jsonjson或xml祈求返回格式示例：Post:http:/ip:端口/v2/whitelist?appid=100001&ebid=0001&transid=1001&opr_code=01&serv_code=&msisdn=&token=E4805d16520de693a3fe707cdc962045返回值：status ：0,message ：ok,result ：msisdn:xxxxxxxxxxx,servCode:xxxxxxx,优先级类型:优先级:,oprCode:01,errCode:顾客余额信息实时查询能力服务地址： http:/ip:端口/v2/balancerealsingle提供单个MSISDN号卡顾客余额实时查询功能 祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无现网手机号output否jsonjson或xml祈求返回格式示例：Post:http:/ip:端口/v2/balancerealsingle?appid=100001&ebid=0001&transid=1001&msisdn=&token=E4805d16520de693a3fe707cdc962045返回值：status ：0,message ：ok,result ：banlance:10000.00依照IP地址查询GPRS信息服务地址： http:/ip:端口/v2/gprsinfo提供单个MSISDN号卡顾客余额实时查询功能 祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密Ip是无192.168.1.1IP地址output否jsonjson或xml祈求返回格式示例：Post:http:/ip:端口/v2/gprsinfo?appid=100001&ebid=0001&transid=1001&ip=192.168.1.1&token=E4805d16520de693a3fe707cdc962045返回值：status ：0,message ：ok,result ：ip:,192.168.1.1,apn: ，rat: ,.等信息码号信息查询能力服务地址： http:/ip:端口/v2/cardinfo提供单个MSISDN号卡顾客余额实时查询功能 祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密card_info是无msisdn/imsi/iccidtype是无00-msisdn 1-imsi 2-iccidoutput否jsonjson或xml祈求返回格式示例：Post:http:/ip:端口/v2/cardinfo?appid=100001&ebid=0001&transid=1001&card_info=xxx&type=0&token=E4805d16520de693a3fe707cdc962045返回值：status ：0,message ：ok,result ：msisdn:xxxxxx,imsi:xxxxxx,iccid :xxxxxx顾客GPRS使用查询:服务地址： http:/ip:端口/v2/ gprsusedinfosingle返回日期GPRS使用量，单位KB祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1所查询专网号码query_date是无1111所查询日期output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/locationinforealingles?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1&query_date=1016返回值：status ：0,message ：ok,result ：gprs:100000顾客短信使用查询服务地址： http:/ip:端口/v2/smsusedinfosingle返回指定日期短信使用条数祈求参数阐明:参数与否必要默认值格式举例含义Appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派Transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成Token是无E4805d16520de693a3fe707cdc962045加密Msisdn是无1所查询专网号码query_date是无1111所查询日期Output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/locationinforealingles?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1&query_date=1016返回值：status ：0,message ：ok,result ：sms:100批量顾客GPRS使用查询服务地址： http:/ip:端口/v2/ gprsusedInfo集团下每个顾客GPRS使用量祈求参数阐明:参数与否必要默认值格式举例含义Appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派Transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成Token是无E4805d16520de693a3fe707cdc962045加密Output否jsonjson或xml祈求返回格式query_date是无1010查询开始时间page_size否1010返回记录数量，默以为10条记录，最大可设立为20条page_num否00、1、2分页页码，默以为0。 0代表第一页，1代表第二页，以此类推。 如果设立了此字段，则输出成果中具有total字段。示例：http:/ip:端口/v2/ gprsusedInfo?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045& query_date =1010&page_size=10&page_num=0返回值：status ：0,message ：ok,result :Msisdn:2,gprs:10000,Msisdn:3,gprs:0,Msisdn:4,gprs:30000批量顾客短信使用查询服务地址： http:/ip:端口/v2/ smsusedinfo返回短信失败记录相应数据祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密output否jsonjson或xml祈求返回格式query_date是无1010查询开始时间page_size否1010返回记录数量，默以为10条记录，最大可设立为20条page_num否00、1、2分页页码，默以为0。 0代表第一页，1代表第二页，以此类推。 如果设立了此字段，则输出成果中具有total字段。示例：http:/ip:端口/v2/ smsusedinfo?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045& query_date =1010&page_size=10&page_num=0返回值：status ：0,message ：ok,result :Msisdn:2,sms:10000,Msisdn:3,sms:0,Msisdn:4,sms:30000顾客当月GPRS查询服务地址： http:/ip:端口/v2/ gprsuusedinfosingle返回指定号码截止到当前时刻为止本月所有GPRS使用量，单位KB祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/ gprsuusedinfosingle?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1返回值：status ：0,message ：ok,result ：toalgprs:3000顾客当月短信查询服务地址： http:/ip:端口/v2/smsusedinfosingle返回指定号码截止到当前时刻为止本月所有短信使用量祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/ smsusedinfosingle?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1返回值：status ：0,message ：ok,result ：toalgprs:3000开关机信息实时查询服务地址： http:/ip:端口/v2/ onandoffrealsingle 返回开关机状态：“1”表达开机，“0”表达关机祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密Msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/onandoffrealsingle?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1返回值：status ：0,message ：ok,result ：status:1在线信息实时查询服务地址： http:/ip:端口/v2/ gprsrealsingle 返回GPRS成果bean，涉及：IP地址、APN、RAT等信息祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式示例：http:/ip:端口/v2/ gprsrealsingle?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1返回值：status ：0,message ：ok,result ：IP：127.0.0.1,APN:”cmnet”,RAT:”233”异常状态顾客批量查询服务地址： http:/ip:端口/v2/ abnormaluserinfo返回该集团所有状态异常（非正常状态）顾客手机号码、状态、状态变更时间、当前时间祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密output否jsonjson或xml祈求返回格式page_size否1010返回记录数量，默以为10条记录，最大可设立为20条page_num否00、1、2分页页码，默以为0。 0代表第一页，1代表第二页，以此类推。 如果设立了此字段，则输出成果中具有total字段。示例：http:/ip:端口/v2/ abnormaluserinfo?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&page_size=10&page_num=0返回值：status ：0,message ：ok,result :Msisdn:2,Status:”正常”,changedate：1110,statusdate：1114,Msisdn:2,Status:1,changedate：1110,statusdate：1114欠费停机顾客批量查询服务地址： http:/ip:端口/v2/ arrearageuserinfo()返回该集团所有欠费停机顾客手机号码、状态、状态变更时间、当前时间祈求参数阐明:参数与否必要默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无0001事务ID，每次加1，用于判断与否是重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密output否jsonjson或xml祈求返回格式page_size否1010返回记录数量，默以为10条记录，最大可设立为20条page_num否00、1、2分页页码，默以为0。 0代表第一页，1代表第二页，以此类推。 如果设立了此字段，则输出成果中具有total字段。示例：http:/ip:端口/v2/ arrearageuserinfo?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&page_size=10&page_num=0返回值：status ：0,message ：ok,result :Msisdn:2,Status:”欠费”,changedate：1110,statusdate：1114,Msisdn:2,Status:“欠费”,changedate：1110,statusdate：1114错误码信息错误码阐明0对的1数据库错误2数据库无记录3定购关系鉴权不通过4应用状态不正常5顾客名与密码鉴权不通过6IP地址鉴权不通过7Token鉴权不通过8白名单鉴权不通过9已超过最大流控限制99系统错误100HLR通信无响应101HLR通信失败阐明：错误码定义规则。0-99 做为公共错误码号段使用。100-199 做为HLR通信类错误码号段使用。200-299 做为PBOSS通信类错误码号段使用。300-399 做为网关通信类错误码号段使用。400-499 做为数据校验时错误码号段使用。