1. 概述

与SOAP相比，REST WebService简化了调用，也降低了技能要求。

REST 近年来已经成为最主要的 Web 服务设计模式。 事实上，REST 对 Web 的影响非常大，由于其使用相当方便，已经普遍地取代了基于 SOAP 和 WSDL 的接口设计。

您可以不用知道REST是什么，按照我们的手册发起HTTP请求即可，只需遵从以下的基本原则

1 REST用URL来描述资源，如人员、部门、协同、公文。

2 使用HTTP协议的GET、POST、PUT和DELETE来描述资源的获取、创建、修改和删除。

请注意，所有的REST服务都必须传递通过验证服务获取的token，以下不再赘述。

1.1. 启用RESTFul web service

协同安装完成以后是不能直接使用RESTFul web service的，需要系统管理员登录系统，在信息集成配置 → REST用户管理模块中添加REST用户并启用该用户即可。

系统管理员创建REST用户后需要对REST用户进行资源授权，REST用户只能访问已经授权的资源。

1.2. 配置开发环境

启动服务，查看RESTFull web service服务的WADL：

http://ip:port/seeyon/rest/application.wadl

例如：http://127.0.0.1:8080/seeyon/rest/application.wadl

1.3. 验证服务

使用创建的REST用户访问RESTFul web service时首先要进行身份验证获取token，所有服务都必须提供合法的令牌ID方可调用。

为保证安全，验证服务必须使用POST方式，用户名和密码使用请求Body以JSON格式发送。

接口调用请求说明

http请求方式：POST

http://ip:port/seeyon/rest/token

原始的HTTP请求如下所示

POST http://127.0.0.1/seeyon/rest/token HTTP/1.1

Host: 127.0.0.1

Accept: application/json

Content-Type: application/json

{"userName":"rest","password":"123456"}

请求实例:

http://IP:port/seeyon/rest/token/{restusername}/{password}

参数说明

参数

是否必须

说明

userName

是

REST用户登录名

password

是

REST用户密码

返回说明

成功返回JSON字符串，失败返回-1。

成功：

{"id": "013a2a1e-a0b0-4f66-b533-da0563f89c6c"}

失败：

{"id": "-1"}

1.3.1. 验证服务增加设置当前登录人员(Since:V6.0)

验证服务服务接口可以绑定设置当前OA登录人员。

接口调用请求说明：

请求示例：

http://ip:port/seeyon/rest/token/{restusername}/{password}？loginName={loginName}

或

http://ip:port/seeyon/rest/token/{restusername}/{password}？memberCode={memberCode}

参数说明

参数

是否必须

说明

userName

是

REST用户登录名

password

是

REST用户密码

loginName

否

OA用户登录名

memberCode

否

OA用户编码，since 7.1

7.1之前loginName为必填；7.1之后loginName与memberCode任选一个参数即可。

返回说明

成功返回JSON字符串，失败返回 :找不到页面

成功：

{"bindingUser":"..."

"id": "013a2a1e-a0b0-4f66-b533-da0563f89c6c"}

失败：

{"id": "-1"}

1.4. 获取Token是否校验绑定IP(Since:V5.6)

新建REST 帐号时，通过是否勾选【获取Token是否校验IP】来设置在获取Token时，是否对当前请求的IP做校验。

参数说明

参数

是否勾选

说明

获取token是否校验绑定IP

勾选

获取token时校验IP，如果与【绑定IP】设置不同，无法获取token

获取token是否校验绑定IP

不勾选

不对请求IP做校验

1.5. 传递Token

除了验证服务，所有的REST调用时必须传递Token，如果不传递Token或传递错误的Token，将返回HttpStatus.SC_UNAUTHORIZED401错误及错误信息。

Token的生命周期为15分钟，如果15分钟无调用，Token将失效，失效以后调用返回401，提示“Invalid token,please authenticate again”。

Token的传递方式有两种：

1 在HTTP请求的header中，使用token属性

GET http://127.0.0.1/seeyon/rest/xxx HTTP/1.1

Host: 127.0.0.1

Accept: application/json

Content-Type: application/json;charset=UTF-8

User-Agent: Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/32.0.1700.76 Safari/537.36

Cookie: JSESSIONID=5079B8DC8A4BD52E48FBA4DE78C2A43C

token:xxxxxxx

2 在请求参数中传递，如

http://127.0.0.1/seeyon/rest/orgMember/123?token=xxxxxxx

如果您使用的是我们的客户端，调用client.authenticate(userName, password);即可。