入门

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，并创建其他企业管理员。在访问权限上，企业管理员拥有最高的权限，可以看到自己的企业 ID 下所有 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 下创建一个新的用户

注意: POST的数据需要是JSON格式的，并设置Content-Type 为 application/json。

Path : /easemob-demo/chatdemoui/users
HTTP Method : POST
Request Headers : {
	   Content-Type : application/json,
	   Authorization : Bearer ${token}
}
Request Body : {"username":"stliu1", "password":"123456"}

删除一个用户

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 服务的示例代码，可以在这里找到。