入门

REST（Representational State Transfer）是一种轻量级的 Web Service 架构风格，可以翻译成“表述性状态转移”，实现和操作明显比 SOAP 和 XML-RPC 更为简洁，可以完全通过 HTTP 协议实现，还可以利用缓存 Cache 来提高响应速度，性能、效率和易用性上都优于SOAP协议。

REST 架构遵循了 CRUD 原则，CRUD 原则对于资源只需要四种行为：Create（创建）、Read（读取）、Update（更新）和Delete（删除）就可以完成对其操作和处理。这四个操作是一种原子操作，对资源的操作包括获取、创建、修改和删除资源的操作正好对应 HTTP 协议提供的 GET、POST、PUT 和 DELETE 方法，因此 REST 把 HTTP 对一个 URL 资源的操作限制在 GET、POST、PUT 和 DELETE 这四个之内。这种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。

更多 REST API 背景知识可以参考RESTful API 设计指南。

平台提供的是一个多租户用户体系，资源以集合（Collection）的形式来描述，这里所说的 Collection 包括 DataBase、企业（orgs）、应用（apps）、IM 用户（users）、群组（chatgroups）、消息（chatmessages）、文件（chatfiles）等等，之间的包含关系是：

• DB = {org1, org2, …}
• org = {app1, app2, …}
• app = {users, messages, chatfiles, chatmessages, chatgroups, …}
• users = {user1, user2, …}
• messages = {message1, message2, …}
• chatfiles = {chatfile1, chatfile2, …}
• chatmessages = {chatmessage1, chatmessage2, …}
• chatgroups = {group1, group2, …}

多租户是指软件架构支持一个实例服务多个用户（Customer），每一个用户被称之为租户（Tenant），软件给予租户可以对系统进行部分定制的能力，如用户界面颜色或业务规则，但是他们不能定制修改软件的代码。

其实在云计算领域，多租户的含义已被扩展。例如，软件即服务（SaaS）提供者，利用运行在一个数据库实例上的应用系统，向多个用户提供 Web 访问服务。在这样的场景下，租户之间的数据是隔离的，并且保证每个用户的数据对其他租户不可见。

在环信服务体系中，不同 org 之间的用户数据相互隔离，同一个 org 下不同 APP 之间的用户数据相互隔离。

环信的服务器端接口都是通过 REST服务方式提供的，REST API 基于最简单的 HTTP 协议，在各个编程语言中都提供了良好的支持。

REST client 就是调用 REST API 的程序端，调用方式有多种：Linux curl、浏览器、编程语言 HTTP 请求访问实现等。

调用 REST API，本质就是发送 HTTP 请求，只不过大家常用的可能是 HTTP GET 和 HTTP POST 请求，但是在 REST 里面还经常用到 HTTP PUT 和 HTTP DELETE。在 REST 中，把这四种操作称之为动词，可以（但不是特别准确）想象成增删改查。

而动词所操作的对象，在 REST 中，被称之为“资源”，也就是 URL，而这些也都是标准的 HTTP 协议的内容。实际上，当我们在浏览器中打开一个网站的时候，例如，打开环信官网，浏览器实际上发送给网站服务器的，就是一个 HTTP GET 的请求。

需要注意的是，环信的 REST API 都是基于 JSON 的，所以在构造 HTTP 请求的时候，需要在 HTTP HEADER 中指明：

在 Java 中，REST Client 实现方式有多种，比如 JBOss RestEasy、Sun Jersey、Dropwizard、Apache HTTPClient。我们推荐使用 Jersey 来调用环信的 REST 服务。

Jersy 2.x 实现了 JAX-RS 2.0 的规范，并且提供了异步的支持，但是 Jersey 2.x 需要 JDK 1.7 的支持，所以如果你的服务器端程序还没有办法使用 JDK 1.7，那么需要使用 Jersey 1.x 的版本。也有很多人直接使用 Apache HTTP Client，我们并不推荐直接使用这个库，主要是因为这个库相对比较底层，需要自己处理的东西很多，API 也相对繁琐。

对于 Python 程序，我们推荐使用 Requests 这个类库来调用环信的 REST 服务。

当用户在环信开发者管理后台中注册的时候，需要填写一个“企业 ID”，这是因为环信是一个支持多租户的云服务平台，并且环信是支持“企业”（或者理解成团队）-“APP”两级结构的。即，在环信平台中，每个企业 ID之间的数据都是严格相互隔离的，而每个企业 ID 内部的每个 APP 之间的数据，也都是严格相互隔离的。

可以想象这样的模型：一个公司中有三个部门，每个部门负责一个 APP，那么这个公司可以注册一个环信的账号，然后在这个账号的名下创建三个（环信中的）APP，每个环信中的 APP 对应一个部门的 APP。

这样，最开始注册的时候的账号，是这个企业在环信中的企业管理员账号，企业管理员可以创建新的 APP，并且指派 APP 管理员账号。在访问权限上，企业管理员拥有最高的权限，可以看到自己的企业 ID 下所有 APP 中的所有的数据，而 APP 管理员则只能看到自己 APP 中的数据，看不到其它 APP 中的数据。同时，上面也说过了，同一个企业 ID 下面的 APP 之间，数据也都是相互隔离的，所以完全可以在两个 APP 中创建相同用户名的用户。

另，如果只是个人开发者开发一个 APP 的话，那么企业 ID 可以随便填写，只需要不和环信现有的企业 ID 重复即可。

最后，因为环信提供的是 REST 服务，并且上面说过，REST 本质就是通过 GET/POST/PUT/DELETE 来操作资源（URL）。所以，实际上可以看到在环信的 REST API 中，也体现了这种思想。

假设一个企业 ID 为 easemob-demo，然后这个企业下面有个 APP 名字叫做 chatdemoui，那么环信的 REST API 就是下面的样子。

获取这个 APP 下的所有用户

Path : /easemob-demo/chatdemoui/users
HTTP Method : GET
Request Headers : {
    	Authorization : Bearer ${token}
}

获取这个 APP 下的用户 stliu 的详情

Path : /easemob-demo/chatdemoui/users/stliu
HTTP Method : GET
Request Headers : {
	   Authorization : Bearer ${token}
}

在这个 APP 下创建一个新的用户

Path : /easemob-demo/chatdemoui/users
HTTP Method : POST
Request Headers : {
	   Content-Type : application/json,
	   Authorization : Bearer ${token}
}
Request Body : {"username":"stliu1", "password":"123456"}
//注意: post的数据需要是json格式的，并设置Content-Type 为 application/json

删除一个用户

Path : /easemob-demo/chatdemoui/users/stliu
HTTP Method : DELETE
Request Headers : {
    	Authorization : Bearer ${token}
}

从上面的 URL 的规则中，也能够看出“企业”–“APP”–“用户”的层层递进的关系。

名词解释

环信的 REST 服务完全是基于 HTTPS 的安全协议，从协议层面保证了在调用的时候，不会被别人窃取到。

环信的后台服务 API 在安全上，是基于 OAuth 2.0 标准的和 RBAC（基于角色的访问控制）的权限模型的。

在调用环信的后台服务之前，需要先登录获取 token，而根据请求发起人的角色不同，获取 token 的方式也不同。

关于 OAuth 2.0，可以参考理解OAuth 2.0。

环信提供了如何调用 REST 服务的示例代码，可以在这里找到。