Restful接口指导规则完整解读

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参数，避免一次性查询，某些参数需有默认值设定。含义第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派事务ID，每次加1，用于判断与否是重放袭击能力id，运管平台生成加密msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式服务地址：端口/v2/userstatusrealsingle提供顾客状态信息实时查询祈求参数阐明:示例：端口/v2/userstatus?appid=100001&ebid=0001&transid=1001返回值：附录：运管平台某些API规则顾客状态查询：参数与否必要默认值格式举例appid是无‘100001’transid是无‘0001’ebid是无0001token是无E4805d16520de693a3fe707cdc962045&token=E4805d16520de693a3fe707cdc962045&msisdn=1{status：0,message：ok,result：{与否参数默认值格式举例含义必要appid是无‘100001’第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派transid是无‘0001’事务ID，每次加1，用于判断与否是begin_time是无1010查询开始时间查询时间范畴：3个月内记录服务地址：端口/v2/smsfaulthistory1返回短信失败记录相应数据祈求参数阐明:status:’00’}}短信失败记录历史查询：有LIST传递待定重放袭击ebid是无0001能力id，运管平台生成token是无E4805d16520de693a3fe707cdc962045加密msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式示例：端口/v2/smsfaulthistory1?appid=100001&ebid=0001&transid=1001&token=E4805d16520de693a3fe707cdc962045&msisdn=1&begintime=1010&endtime=1111返回值：服务地址：端口/v2/locationinforealsingle返回顾客位置信息(经纬度){status：0,message：ok,result:[{}]}顾客实时位置信息查询end_time是无1111查询结束时间查询时间范畴：3个月内记录page_size否1010page_num否00、1、2返回记录数量，默以为10条记录，最大可设立为20条分页页码，默以为0。0代表第一页，1代表第二页，以此类推。如果设立了此字段，则输出成果中具有total字段。含义第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派事务ID，每次加1，用于判断与否是重放袭击能力id，运管平台生成加密msisdn是无1所查询专网号码output否jsonjson或xml祈求返回格式示例：端口93a3fe707cdc962045&msisdn=1返回值：参数与否必要默认值格式举例appid是无‘100001’transid是无‘0001’ebid是无0001token是无E4805d16520de693a3fe707cdc962045/v2/locationinforealingles?appid=100001&ebid=0001&transid=1001&token=E4805d16520de6{status：0,message：ok,result：{lat:39.920411，lng：116.418224}}祈求参数阐明:含义第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派事务ID，每次加1，用于判断与否是重放袭击能力id，运管平台生成加密query_date是无1111所查询专网号码output否jsonjson或xml祈求返回格式服务地址：端口/v2/locationinforealsingle返回该集团指定日期顾客总数祈求参数阐明:示例：端口/v2/locationinforealsingle?appid=100001&ebid=0001集团顾客数查询参数与否必要默认值格式举例appid是无‘100001’transid是无‘0001’ebid是无0001token是无E4805d16520de693a3fe707cdc962045&query_date=1016&token=E4805d16520de693a3fe707cdc962045&msisdn=1{status：0,message：ok,result：{totla:0返回值：含义第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派事务ID，每次加1，用于判断与否是重放袭击能力id，运管平台生成加密query_date是无1111所查询专网号码output否jsonjson或xml祈求返回格式服务地址：端口/v2/gprspoolinfo查询集团流量池顾客数和大小祈求参数阐明:示例：端口/v2/gprspoolinfo?appid=100001&ebid=0001&transid=1001返回值：}}流量池信息查询参数与否必要默认值格式举例appid是无‘100001’transid是无‘0001’ebid是无0001token是无E4805d16520de693a3fe707cdc962045&query_date=1016&token=E4805d16520de693a3fe707cdc962045{status：0,含义第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派事务ID，每次加1，用于判断与否是重放袭击能力id，运管平台生成加密query_date是无1111所查询专网号码output否jsonjson或xml祈求返回格式服务地址：端口/v2/gprspoolusedinfo查询集团流量池指定月份流量使用状况祈求参数阐明:示例：端口message：ok,result：{usersCount:10000,size:10240}}流量池使用量查询参数与否必要默认值格式举例appid是无‘100001’transid是无‘0001’ebid是无0001token是无E4805d16520de693a3fe707cdc962045/v2/gprspoolusedinfo?appid=100001&ebid=0001&transid=1001&query_date=1016&token=E4含义第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派事务ID，每次加1，用于判断与否是重放袭击能力id，运管平台生成加密opr_code是无01oprCode--操作类型01增长02删除返回值：服务地址：端口/v2/whitelist依照指定短信接入号和手机号列表进行短信白名单数据添加或删除祈求参数阐明:{status：0,message：ok,result：{gprsUserd:Balance:10000}}短信白名单管理参数与否必要默认值格式举例appid是无‘100001’transid是无‘0001’ebid是无0001token是无E4805d16520de693a3fe707cdc962045805d16520de693a3fe707cdc962045serv_codemsisdnoutput示例：Post:端口/v2/whitelist?appid=100001&ebid=0001&transid=1001返回值：是无短信接入号是否无jsonjson或xml现网手机号祈求返回格式&opr_code=01&serv_code=&msisdn=&token=E4805d16520de693a3fe707cdc962045{status：0,message：ok,result：{msisdn:’xxxxxxxxxxx’,servCode:’xxxxxxx’,优先级类型:’’优先级:’’,oprCode:’01’,errCode:’’}}含义第三方应用唯一标示，由全网管理员在运营管理平台应用上线时分派事务ID，每次加1，用于判断与否是重放袭击能力id，运管平台生成加密msisdn是无现网手机号output否jsonjson或xml祈求返回格式服务地址：端口/v2/balancerealsingle提供单个MSISDN号卡顾客余额实时查询功能祈求参数阐明:示例：Post:端口顾客余额信息实时查询能力参数与否必要默认值格式举例appid是无‘100001’transid是无‘0001’ebid是无0001token是无E4805d16520de693a3fe707cdc962045/v2/balancerealsingle?appid=100001&ebid=0001&transid=1001&msisdn=&token=E4805d16520de693a3fe707cdc962045{status：0,message：ok,result：{返回值：服务地址：端口/v2/gprsinfo提供单个MSISDN号卡顾客余额实时查询功能祈求参数阐明:示例：Post:端口/v2/gprsinfo?appid=100001&ebid=0001&transid=1001&ip=192.168.1.1&toke