====== 入门 ======

----

===== 环信服务器端 REST 平台概述 =====

==== 关于REST ====

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 背景知识可以参考[[http://www.ruanyifeng.com/blog/2014/05/restful_api.html|RESTful API 设计指南]]。

==== REST平台体系 ====

平台提供的是一个多租户用户体系，资源以集合（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 server ====

环信的服务器端接口都是通过 [[http://zh.wikipedia.org/zh-cn/REST|REST服务]]方式提供的，REST API 基于最简单的 HTTP 协议，在各个编程语言中都提供了良好的支持。

==== REST client ====

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

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

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

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

^Header_name	^Header_value	^Description ^
|Accept	|application/json	|服务器端返回给客户端的数据类型|
|Content-Type	|application/json	|客户端发到服务器端的是数据类型|

==== Java ====

在 Java 中，REST Client 实现方式有多种，比如 JBOss RestEasy、Sun Jersey、Dropwizard、Apache HTTPClient。我们推荐使用 [[https://jersey.java.net/|Jersey]] 来调用环信的 REST 服务。

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

==== Python ====

对于 Python 程序，我们推荐使用 [[http://docs.python-requests.org/en/latest/|Requests]] 这个类库来调用环信的 REST 服务。

===== 环信服务器基本架构 =====

当用户在[[https://console.easemob.com/|环信开发者管理后台]]中注册的时候，需要填写一个“企业 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 下的所有用户

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

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

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

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

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

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

删除一个用户

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

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

名词解释

^名词	^解 释 ^
|org_name	|企业的唯一标识，开发者在[[https://console.easemob.com/|环信开发者管理后台]]注册账号时填写的企业 ID|
|app_name	|同一”企业”下“APP”唯一标识，开发者在[[https://console.easemob.com/|环信开发者管理后台]]创建应用时填写的“应用名称”|
|org_admin	|开发者在[[https://console.easemob.com/|环信开发者管理后台]]注册时填写的“用户名”。企业管理员拥有对该企业账号下所有资源的操作权限|
|appkey	|一个 APP 的唯一标识，规则是 ${org_name}#${app_name}|

==== 安全 ====

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

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

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

关于 OAuth 2.0，可以参考[[http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html|理解OAuth 2.0]]。

==== 示例代码 ====

环信提供了如何调用 REST 服务的示例代码，可以在[[https://github.com/easemob/emchat-server-examples|这里]]找到。


----
<WRAP group>
<WRAP half column>
上一章节：[[start:000quickstart|快速入门]]
</WRAP>

<WRAP half column>
下一页：[[start:100serverintegration:20users|用户体系集成]]
</WRAP>
</WRAP>