入门


环信服务器端 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 背景知识可以参考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

环信的服务器端接口都是通过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 协议的内容。实际上,当我们在浏览器中打开一个网站的时候,例如,打开环信官网,浏览器实际上发送给网站服务器的,就是一个 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。我们推荐使用 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

对于 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”–“用户”的层层递进的关系。

名词解释

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

安全

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

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

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

关于 OAuth 2.0,可以参考理解OAuth 2.0

示例代码

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


上一章节:快速入门

下一页:用户体系集成