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