Restful接口规则(完整)解读.doc

Restful接口设计规范1、 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。2、 运管平台/烽行平台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是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1064826000001所查询专网号码output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/userstatus?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：status : 0,message : ok,result : status:00 短信失败记录历史查询： 有LIST传递 待定服务地址： http:/ip:端口/v2/smsfaulthistory1返回短信失败记录相应数据请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1064826000001所查询专网号码output否jsonjson或xml请求返回格式begin_time是无20141010查询开始时间查询时间范围：3个月内的记录end_time是无20141111查询结束时间查询时间范围：3个月内的记录page_size否1010返回记录数量，默认为10条记录，最大可设置为20条page_num否00、1、2分页页码，默认为0。 0代表第一页，1代表第二页，以此类推。 如果设置了此字段，则输出结果中含有total字段。示例：http:/ip:端口/v2/smsfaulthistory1?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001&begintime=20141010&endtime=20141111返回值：status : 0,message : ok,result :用户实时位置信息查询服务地址： http:/ip:端口/v2/locationinforealsingle返回用户的位置信息(经纬度)请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1064826000001所查询专网号码output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/locationinforealingles?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：status : 0,message : ok,result : lat:39.920411, lng: 116.418224集团用户数查询服务地址： http:/ip:端口/v2/locationinforealsingle返回该集团指定日期的用户总数请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密query_date是无20141111所查询专网号码output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/locationinforealsingle?appid=100001&ebid=2300000000000001&query_date=20141016&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：status : 0,message : ok,result : totla:20000流量池信息查询服务地址： http:/ip:端口/v2/gprspoolinfo查询集团流量池的用户数和大小请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密query_date是无20141111所查询专网号码output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/gprspoolinfo?appid=100001&ebid=2300000000000001&transid=2014101615030000001&query_date=20141016&token=E4805d16520de693a3fe707cdc962045返回值：status : 0,message : ok,result : usersCount:10000,size:10240流量池使用量查询服务地址： http:/ip:端口/v2/gprspoolusedinfo查询集团流量池指定月份的流量使用情况请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密query_date是无20141111所查询专网号码output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/gprspoolusedinfo?appid=100001&ebid=2300000000000001&transid=2014101615030000001&query_date=20141016&token=E4805d16520de693a3fe707cdc962045返回值：status : 0,message : ok,result : gprsUserd:2000Balance:10000短信白名单管理服务地址： http:/ip:端口/v2/whitelist根据指定短信接入号和手机号列表进行短信白名单数据的添加或删除 请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密opr_code是无01oprCode-操作类型 01 增加 02 删除serv_code是无10648000001短信接入号msisdn是网手机号output否jsonjson或xml请求返回格式示例：Post:http:/ip:端口/v2/whitelist?appid=100001&ebid=2300000000000001&transid=2014101615030000001&opr_code=01&serv_code=10648000001&msisdntoken=E4805d16520de693a3fe707cdc962045返回值：status : 0,message : ok,result : msisdn:xxxxxxxxxxx,servCode:xxxxxxx,优先级类型:优先级:,oprCode:01,errCode:用户余额信息实时查询能力服务地址： http:/ip:端口/v2/balancerealsingle提供单个MSISDN号卡的用户余额实时查询功能 请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是网手机号output否jsonjson或xml请求返回格式示例：Post:http:/ip:端口/v2/balancerealsingle?appid=100001&ebid=2300000000000001&transid=2014101615030000001&msisdntoken=E4805d16520de693a3fe707cdc962045返回值：status : 0,message : ok,result : banlance:10000.00根据IP地址查询GPRS信息服务地址： http:/ip:端口/v2/gprsinfo提供单个MSISDN号卡的用户余额实时查询功能 请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密Ip是无IP地址output否jsonjson或xml请求返回格式示例：Post:http:/ip:端口/v2/gprsinfo?appid=100001&ebid=2300000000000001&transid=2014101615030000001&ip=&token=E4805d16520de693a3fe707cdc962045返回值：status : 0,message : ok,result : ip:,,apn: , rat: ,.等信息码号信息查询能力服务地址： http:/ip:端口/v2/cardinfo提供单个MSISDN号卡的用户余额实时查询功能 请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密card_info是无msisdn/imsi/iccidtype是无00-msisdn 1-imsi 2-iccidoutput否jsonjson或xml请求返回格式示例：Post:http:/ip:端口/v2/cardinfo?appid=100001&ebid=2300000000000001&transid=2014101615030000001&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是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1064826000001所查询专网号码query_date是无20141111所查询日期output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/locationinforealingles?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001&query_date=20141016返回值：status : 0,message : ok,result : gprs:100000用户短信使用查询服务地址： http:/ip:端口/v2/smsusedinfosingle返回指定日期的短信使用条数请求参数说明:参数是否必须默认值格式举例含义Appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配Transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成Token是无E4805d16520de693a3fe707cdc962045加密Msisdn是无1064826000001所查询专网号码query_date是无20141111所查询日期Output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/locationinforealingles?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001&query_date=20141016返回值：status : 0,message : ok,result : sms:100批量用户GPRS使用查询服务地址： http:/ip:端口/v2/ gprsusedInfo集团下每个用户的GPRS使用量请求参数说明:参数是否必须默认值格式举例含义Appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配Transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成Token是无E4805d16520de693a3fe707cdc962045加密Output否jsonjson或xml请求返回格式query_date是无20141010查询开始时间page_size否1010返回记录数量，默认为10条记录，最大可设置为20条page_num否00、1、2分页页码，默认为0。 0代表第一页，1代表第二页，以此类推。 如果设置了此字段，则输出结果中含有total字段。示例：http:/ip:端口/v2/ gprsusedInfo?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045& query_date =20141010&page_size=10&page_num=0返回值：status : 0,message : ok,result :Msisdn:1064822222222,gprs:10000,Msisdn:1064833333333,gprs:20000,Msisdn:1064844444444,gprs:30000批量用户短信使用查询服务地址： http:/ip:端口/v2/ smsusedinfo返回短信失败记录相应数据请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密output否jsonjson或xml请求返回格式query_date是无20141010查询开始时间page_size否1010返回记录数量，默认为10条记录，最大可设置为20条page_num否00、1、2分页页码，默认为0。 0代表第一页，1代表第二页，以此类推。 如果设置了此字段，则输出结果中含有total字段。示例：http:/ip:端口/v2/ smsusedinfo?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045& query_date =20141010&page_size=10&page_num=0返回值：status : 0,message : ok,result :Msisdn:1064822222222,sms:10000,Msisdn:1064833333333,sms:20000,Msisdn:1064844444444,sms:30000用户当月GPRS查询服务地址： http:/ip:端口/v2/ gprsuusedinfosingle返回指定号码截止到目前时刻为止本月所有的GPRS使用量，单位KB请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1064826000001所查询专网号码output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/ gprsuusedinfosingle?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：status : 0,message : ok,result : toalgprs:3000用户当月短信查询服务地址： http:/ip:端口/v2/smsusedinfosingle返回指定号码截止到目前时刻为止本月所有的短信使用量请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1064826000001所查询专网号码output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/ smsusedinfosingle?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：status : 0,message : ok,result : toalgprs:3000开关机信息实时查询服务地址： http:/ip:端口/v2/ onandoffrealsingle 返回开关机状态：“1”表示开机，“0”表示关机请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密Msisdn是无1064826000001所查询专网号码output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/onandoffrealsingle?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：status : 0,message : ok,result : status:1在线信息实时查询服务地址： http:/ip:端口/v2/ gprsrealsingle 返回GPRS结果bean，包括：IP地址、APN、RAT等信息请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1064826000001所查询专网号码output否jsonjson或xml请求返回格式示例：http:/ip:端口/v2/ gprsrealsingle?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：status : 0,message : ok,result : IP: ,APN:”cmnet”,RAT:”233”异常状态用户批量查询服务地址： http:/ip:端口/v2/ abnormaluserinfo返回该集团所有状态异常（非正常状态）的用户的手机号码、状态、状态变更时间、当前时间请求参数说明:参数是否必须默认值格式举例含义appid是无100001第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无2014101615030000001事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力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=10