REST服务接口文档 (2)

REST服务接口文档 (2) 深 圳 市 CMS 系 统 REST 服 务 接 口 文 档 项目代号:CMS-2014-09-15 深圳市定制化服务工作室 2014-10-02 目 录 深圳市绿协管理系统需求规格说明书V1.0 1、 引言..................................................................................... 错误～未定义书签。 1.1、 REST介绍 .................................................................... 错误～未定义书签。 1.1、 编写目的……………………………………………………………………………错误～未定义书签。 1.2、 编写原则....................................................................... 错误～未定义书签。 1.3、 变更历史....................................................................... 错误～未定义书签。 、 我的链接服务列表................................................................ 错误～未定义书签。 2 2.1、 添加标签分类.............................................................................................. 4 2.2、 删除分类标签.............................................................................................. 4 2.3、 更新分类标签.............................................................................................. 4 2.4、 获取分类标签列表....................................................................................... 4 2.5、 添加我的链接连接....................................................................................... 4 2.6 更新我的链接连接....................................................................................... 4 2.7 删除我的链接连接....................................................................................... 4 2.8 查询我的链接连接....................................................................................... 4 深圳市轩蓝创新科技工作室 第 2 页 共 8 页 深圳市绿协管理系统需求规格说明书V1.0 1、 引言 1.1、 REST介绍 REpresentational State Transfer (REST) 是一种原则，其中将 web 服务视为资源， 可以由其 URL 唯一标识。RESTful Web 服务的关键特点是明确使用 HTTP 方法来表 示不同的操作的调用。 REST 的基本设计原则对典型 CRUD 操作使用 HTTP 方法: POST - 创建资源 GET - 检索资源 PUT – 更新资源 DELETE - 删除资源 REST 服务的主要优势在于: 它们是跨平台 (Java、.net、PHP 等)高度可重用的，因为它们都依赖基本 HTTP 协议。 而不是复杂的 SOAP XML，使用非常方便。 它们使用基本的 XML， 基于 REST 的 web 服务日益成为后端企业服务集成的首选方法。与基于 SOAP 的 web 服务相比，它的编程模型简单，而本机 XML(而不是 SOAP )的使用减少了序列 化和反序列化过程的复杂性，并且不再需要其他作用相同的第三方库。 1.2、 编写目的 编写本文的目的是为了将系统功能进行模块化、服务化，将用户的操作以服务的方式提 供。系统与系统之间遵循服务规范，将系统与系统之间的交互转为定制化服务交互，以 实现系统与系统之间的集成。 1.3、 编写原则 可寻址性(Addressability)REST 中的所有东西都基于资源 的概念。资源与 OOP 中的对象或其他名词不同，它是一种抽象，必须可以通过 URI 寻址或访问。 接口一致性(Interface uniformity)与 SOAP 或其他标准不同，REST 要求用来操纵资源的方法或动词不是任意的。这意味着 RESTful 服务的开发人员只能使用 HTTP 支持的方法，比如GET、 PUT、POST、DELETE 等等。因此不需要使用 WSDL 等服务描述语言。 深圳市轩蓝创新科技工作室 第 3 页 共 8 页 深圳市绿协管理系统需求规格说明书V1.0 无状态(Statelessness)为了增强可伸缩性，服务器端不存储客户机的状态信息。这使服务器不与特定的客户机相绑定，负载平衡变得简单多了。这还让服务器更容易监视、更可靠。 具象(Representational)客户机总是与资源的某种具象交互，绝不会直接与资源本身交互。同一资源还可以有多个具象。理论上说，持有资源的具象的任何客户机应该有操纵底层资源的足够信息。 连通性(Connectedness)任何基于 REST 的系统都应该预见到客户机需要访问相关的资源，应该在返回的资源具象中包含这些资源。例如，可以以超链接的形式包含特定 RESTful 服务的操作序列中的相关步骤，让客户机可以根据需要访问它们。 1.4、 变更历史 序号 变更人员 变更时间 变更内容 邵震 我的链接服务2.1、2.2、2.3、2.4、2.5、2.6、2.7、1 2014-10-02 2.8 2、 公共连接服务列表 2.1、 添加公共连接分类 请求方式 PUT 服务路径 /commonlink/add/commonlinktype 路径参数/描述 无 参数类型 application/json 参数描述 {“name”:”分类1”} 备注:name:分类名称 返回值类型 application/json 描述 添加成功:{result:0} 添加失败:{result:1,”id”:”123456”} id:分类id 深圳市轩蓝创新科技工作室 第 4 页 共 8 页 深圳市绿协管理系统需求规格说明书V1.0 不允许重复添加: {result:2} 2.2、 删除公共连接分类 请求方式 DELETE 服务路径 /commonlink/delete/type/{id} 路径参数/描述 id:分类id 参数类型 无 参数描述 无 返回值类型 application/json 描述 添加成功:{result:0} 添加失败:{result:1} 2.3、 更新共连接分类 请求方式 UPDATE 服务路径 /commonlink/update/type/{id} 路径参数/描述 id:分类id 参数类型 application/json 参数描述 {“name”:”分类1”} 备注:name:分类名称 返回值类型 application/json 描述 添加成功:{result:0} 添加失败:{result:1} 深圳市轩蓝创新科技工作室 第 5 页 共 8 页 深圳市绿协管理系统需求规格说明书V1.0 2.4、 获取共连接分类列表 请求方式 GET 服务路径 /commonlink/list/types 路径参数/描述 无 参数类型 无 参数描述 无 返回值类型 application/json 描述 {“list”:[{“id”:”123456”, ”name”:”xxx官网”, ”userid”:”1”, “orderid”:”1”},…,}] id:标签分类 name:标签分类名称 orderid:标签分类排序id 2.5、 添加公共连接 请求方式 PUT 服务路径 /commonlink/add/url 路径参数/描述 无 参数类型 application/json 参数描述 {“name”:”xxx”,”url”:””,”typename”:”type1”,” newwin”:”1”} name:公共连接名称 url:公共连接ur l typename:公共连接分类名称 newwin:是否在新窗口中打开，0表示否，1表示是 返回值类型 application/json 深圳市轩蓝创新科技工作室 第 6 页 共 8 页 深圳市绿协管理系统需求规格说明书V1.0 描述 添加成功:{result:0} 添加失败:{result:1} 不允许往同一类型下添加重‎‎复连接: {result:2} 2.6、 更新公共连接 请求方式 UPDATE 服务路径 /commonlink/update/url 路径参数/描述 无 参数类型 application/json 参数描述 {“name”:”xxx”,”url”:””,”tagname”:”tag1”} name:我的链接连接名称 url:我的链接连接url tagname:标签分类名称 返回值类型 application/json 描述 添加成功:{result:0} 添加失败:{result:1} 2.7、 删除公共连接 请求方式 DELETE 服务路径 /commonlink/delete/url/{id} 路径参数/描述 id:公共连接id 参数类型 application/json 参数描述 {“id”:”连接id”} id: 连接id 返回值类型 application/json 描述 删除成功:{result:0} 删除失败:{result:1} 深圳市轩蓝创新科技工作室 第 7 页 共 8 页 深圳市绿协管理系统需求规格说明书V1.0 2.8、 查询公共连接列表 请求方式 GET 服务路径 /commonlink/find/urls/{tagid} 路径参数/描述 tagid:标签分类id 参数类型 无 参数描述 无 返回值类型 application/json 描述 {“commonlinklist”:[{“id”:”123456”, ”name”:”xxx官网”, “url”:”1”, ”userid”:”1”, },…,}], “count”:20} id:连接id name:连接名称 url:连接url userid:用户id count:链接连接总数 深圳市轩蓝创新科技工作室 第 8 页 共 8 页