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