搜索
Restful接口设计规范一、Restful简介REST是“REpresentationalStateTransfer”的缩写，可以翻译成“表现状态转换”，但是在绝大多数场合中我们只说REST或者RESTful。为什么会起这么一个奇怪的名字呢？我们可以从上述这篇论文中找到答案。Fielding在论文中将REST定位为“分布式超媒体应用（DistributedHypermediaSystem）”的架构风格，它在文中提到一个名为“HATEOAS（Hypermediaastheengineofapplicationstate）”的概念。我们利用一个面向最终用户的Web应用来对这个概念进行简单阐述：这里所谓的应用状态（ApplicationState）表示Web应用的客户端的状态，简单起见可以理解为会话状态。资源在浏览器中以超媒体的形式呈现，通过点击超媒体中的链接可以获取其它相关的资源或者对当前资源进行相应的处理，获取的资源或者针对资源处理的响应同样以超媒体的形式再次呈现在浏览器上。由此可见，超媒体成为了驱动客户端会话状态的转换的引擎。借助于超媒体这种特殊的资源呈现方式，应用状态的转换体现为浏览器中呈现资源的转换。如果将超媒体进一步抽象成一般意义上的资源呈现（Representation）方式，那么应用状态变成了可被呈现的状态（REpresentationalState）。应用状态之间的转换就成了可被呈现的状态装换（REpresentationalStateTransfer），这就是REST。二、运管平台/烽行平台Restful接口标准1.接口命名规则端口/v2/接口名IP：服务器IP地址端口：Restful端口号V2:版本号(2)接口名：命名规则：现有接口方法去第一个单词后，全小写命名，如：用户余额信息实时查询能力，原接口名：queryBalanceRealSingle(Stringmsisdn)Restful接口:端口/v2/balancerealsingle2.参数规则参数提交方式：application/参数命名：单词采取小写，复合词采取下划线分开的全小写命名。参数规则：批量查询需有page_size以及page_num参数，避免一次性查询，部分参数需有默认值设定。附录：运管平台部分API规则用户状态查询：服务地址：端口/v2/userstatusrealsingle提供用户状态信息实时查询请求参数说明:参数是否必须默认值格式举例含义appid是无‘100001’第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无‘2014101615030000001’事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1064826000001所查询专网号码output否jsonjson或xml请求返回格式示例：端口/v2/userstatus?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：{status:0,message:ok,result:{status:’00’}}短信失败记录历史查询：有LIST传递待定服务地址：端口/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字段。示例：端口/v2/smsfaulthistory1?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001&begintime=20141010&endtime=20141111返回值：{status:0,message:ok,result:[{}]}用户实时位置信息查询服务地址：端口/v2/locationinforealsingle返回用户的位置信息(经纬度)请求参数说明:参数是否必须默认值格式举例含义appid是无‘100001’第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无‘2014101615030000001’事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1064826000001所查询专网号码output否jsonjson或xml请求返回格式示例：端口/v2/locationinforealingles?appid=100001&ebid=2300000000000001&transid=2014101615030000001&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：{status:0,message:ok,result:{lat:39.920411,lng:116.418224}}集团用户数查询服务地址：端口/v2/locationinforealsingle返回该集团指定日期的用户总数请求参数说明:参数是否必须默认值格式举例含义appid是无‘100001’第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无‘2014101615030000001’事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密query_date是无20141111所查询专网号码output否jsonjson或xml请求返回格式示例：端口/v2/locationinforealsingle?appid=100001&ebid=2300000000000001&query_date=20141016&token=E4805d16520de693a3fe707cdc962045&msisdn=1064826000001返回值：{status:0,message:ok,result:{totla:20000}}流量池信息查询服务地址：端口/v2/gprspoolinfo查询集团流量池的用户数和大小请求参数说明:参数是否必须默认值格式举例含义appid是无‘100001’第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无‘2014101615030000001’事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密query_date是无20141111所查询专网号码output否jsonjson或xml请求返回格式示例：端口/v2/gprspoolinfo?appid=100001&ebid=2300000000000001&transid=2014101615030000001&query_date=20141016&token=E4805d16520de693a3fe707cdc962045返回值：{status:0,message:ok,result:{usersCount:10000,size:10240}}流量池使用量查询服务地址：端口/v2/gprspoolusedinfo查询集团流量池指定月份的流量使用情况请求参数说明:参数是否必须默认值格式举例含义appid是无‘100001’第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无‘2014101615030000001’事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密query_date是无20141111所查询专网号码output否jsonjson或xml请求返回格式示例：端口/v2/gprspoolusedinfo?appid=100001&ebid=2300000000000001&transid=2014101615030000001&query_date=20141016&token=E4805d16520de693a3fe707cdc962045返回值：{status:0,message:ok,result:{gprsUserd:2000Balance:10000}}短信白名单管理服务地址：端口/v2/whitelist根据指定短信接入号和手机号列表进行短信白名单数据的添加或删除请求参数说明:参数是否必须默认值格式举例含义appid是无‘100001’第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分配transid是无‘2014101615030000001’事务ID，每次加1，用于判断是否是重放攻击ebid是无2300000000000001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密opr_code是无01oprCode--操作类型01增加02删除serv_code是无10648000001短信接入号msisdn是无18211111111现网手机号output否jsonjson或xml请求返回格式示例：Post:端口/v2/whitelist?appid=100001&ebid=2300000000000001&transid=2014101615030000001&opr_code=01&serv_code=10648000001&msisdn=18211111111&token=E4805d16520de693a3fe707cdc962045返回值：{status:0,message:ok,result:{msisdn:’xxxxxxxxxxx’,servCode:’xxxxxxx’,优先级类型:’’优先级:’’,oprCode:’01’,errCode:’’}}用户余额信息实