知识库

1     目标

此规范用于T+对外发布的开放服务的http rest接口。
2     公共HTTP头定义

开放服务的RESTful接口中使用了一些公共请求头。这些请求头可以被所有的请求所使用,其详细定义如下：
名称
描述
Authorization
用于验证请求合法性的认证信息。如4.2.1中所述
Content-Type
application/x-www-form-urlencoded;charset=utf-8
Version
接口版本
Date
当前时间
 
3     签名

对外提供服务时，将对每个请求进行签名验证（Authentication），以确保请求者的合法性。签名验证是通过使用 appKey/appSecret对称加密的方法来验证请求发送者的身份。
加密后的签名字符串经过BASE64编码后，由http请求头（Header）中的Authorization参数进行传递，表示该请求已被授权，可以从对外服务获取到相应的请求数据。
3.1   签名信息

签名字符串由一系列业务处理所需的参数组成，数据格式为JSON。
签名字符串内容示例如下：
Base64{
"appKey":"SYS000001",
"authInfo": Base64 hmac-sha1"{
"uri":"/mail/sendmail/",
"appId":"123",
"orgId":"600588",
"userUid":"123567",
"referer":"机器小助手",
"access_token":"qiwioexmjssiejls"
"date":"Mon, 30 Jun 2014 06:14:04 GMT”
}",
"paramInfo":"{
"uri":"/mail/sendmail/",
"appId":"123",
"orgId":"600588",
"userUid":"123567",
"referer":"机器小助手",
"access_token":"qiwioexmjssiejls"
"date":"Mon, 30 Jun 2014 06:14:04 GMT”
}"
}
签名字符串中各参数说明如下表：
名称
描述

accessKey
即appKey，由BSS分配。
必填
uri
资源路径规范，同本文第四章节介绍
必填
appId
第三方应用调用开放服务时的应用标示，来源于BSS
可选
orgId
组织ID，来自于BSS，包含企业id和isv id。
可选
userId
用户ID，来自于BSS。
可选
referer
第三方应用的什么功能调用了开放服务的相关接口。
唯一的字符串，应简洁、含义明确，可以不填写。
可选
access_token
用户登录之后平台下发的token
可选
date
当前时间
必填
 
3.2   签名方式

各业务根据数据安全和性能来选择安全加密方式。
名称
描述
hmac_sha1＋base64
安全性较高
 
4     资源路径规范

资源路径格式：
${host}/${资源类型}/${资源方法}
名称
描述
Host
接口服务域名或者ip以及端口
资源类型
TPlus/api/v1/[/资源名称]
资源方法
[/方法][?参数名=参数值]
资源名称首字母小写，如果是词组第二个词以后每个首字母大写。
 
5     数据格式规范

    5.1 提交数据的格式

_args={argName:value[,argName1:value1]}，其中等号之后的值是urlencoded。
    5.2 响应数据的格式

直接返回值或对象的Json序列化结果，
例如：
{Code:”100”,Name:”aa”}
[1,2,3,4]
true
6     异常格式与编码

访问开放服务出现错误时，开放服务会返回的Http头中的响应号为400至500,并在响应体中返回具体错误码和错误信息, 便于定位问题,并做出适当的处理。
6.1   错误相应格式

单次请求返回的数据为JSON格式如下：
1
2
3
4
{
"code":${code},
"message":${message}
}
批量提交请求返回的数据为JSON格式如下：
{
         "code":${code},
         "message":${message}
         "data":{
                   "[externalCode|index]":{
                            "code":${code},
                            "message":${message}
                   },
                   "[externalCode|index]":{
                            "code":${code},
                            "message":${message}
                   }
         }
}
注："[externalCode|index]" ，默认使用externalCode，当externalCode为空则返回批量列表的index（index从0开始）。

6.2   错误码字段描述

字段
介绍
要求
备注
 code
错误编码
 必填、字符串或者数据

message
对应的错误信息提示
 必填、字符串

httpstatus
http状态
 可选、数字

data
附加的错误数据
 可选、Json

id
错误编码
 可选

exception
内部错误堆栈
 可选、json

6.3   附录http状态码参考

6.3.1   HTTP状态码：

状态码
信息
200~299
成功状态码
300~399
重定向状态码
400~499
业务端（客户端）错误状态码
500~599
服务器错误状态码
      
6.3.2   常用的HTTP状态码：

状态码
原因
信息编码
表达的意义
200
OK
OK
请求成功
400
Bad Request
Bad Request
请求格式非法
403
Forbidden
Forbidden
请求被服务器拒绝
404
Not Found
Not Found
请求的资源未找到
405
Method not allowed
Method not allowed
不支持该请求方法
415
Unsupported media type
Unsupported media type
未知或者不支持的文档类型
500
Internal server error
Internal server error
服务器内部错误