资源描述
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/balancerealsingle
2. 参数规则
参数提交方式：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
否
json
json或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
否
json
json或xml
祈求返回格式
begin_time
是
无
1010
查询开始时间
查询时间范畴：3个月内记录
end_time
是
无
1111
查询结束时间
查询时间范畴：3个月内记录
page_size
否
10
10
返回记录数量，默以为10条记录，最大可设立为20条
page_num
否
0
0、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
否
json
json或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
否
json
json或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
否
json
json或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
否
json
json或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
是
无
01
oprCode--操作类型 01 增长 02 删除
serv_code
是
无
短信接入号
msisdn
是
无
现网手机号
output
否
json
json或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
否
json
json或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.1
IP地址
output
否
json
json或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/iccid
type
是
无
0
0--msisdn 1--imsi 2--iccid
output
否
json
json或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
否
json
json或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
否
json
json或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
否
json
json或xml
祈求返回格式
query_date
是
无
1010
查询开始时间
page_size
否
10
10
返回记录数量，默以为10条记录，最大可设立为20条
page_num
否
0
0、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
否
json
json或xml
祈求返回格式
query_date
是
无
1010
查询开始时间
page_size
否
10
10
返回记录数量，默以为10条记录，最大可设立为20条
page_num
否
0
0、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
否
json
json或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
否
json
json或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
否
json
json或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
否
json
json或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
否
json
json或xml
祈求返回格式
page_size
否
10
10
返回记录数量，默以为10条记录，最大可设立为20条
page_num
否
0
0、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
否
json
json或xml
祈求返回格式
page_size
否
10
10
返回记录数量，默以为10条记录，最大可设立为20条
page_num
否
0
0、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
顾客名与密码鉴权不通过
6
IP地址鉴权不通过
7
Token鉴权不通过
8
白名单鉴权不通过
9
已超过最大流控限制
99
系统错误
100
HLR通信无响应
101
HLR通信失败
阐明：错误码定义规则。
0-99 做为公共错误码号段使用。
100-199 做为HLR通信类错误码号段使用。
200-299 做为PBOSS通信类错误码号段使用。
300-399 做为网关通信类错误码号段使用。
400-499 做为数据校验时错误码号段使用。
展开阅读全文
浙ICP备2021020529号-1 | 浙B2-20240490 
