新版群组/聊天室服务 REST API差异说明v2

(最新更新时间: 2017-01-06)

第一版差异说明发出后，我们收到了一些开发者的反馈。根据这些反馈，我们对新版群组/聊天室的异常、状态码进行了调整和优化。相比2017-01-03第一个版本，主要更新内容：

• com.easemob.group.exception.ForbiddenOpException 异常类型的状态码 由400变成403，该异常表示本次调用不符合群组/聊天室操作的正确逻辑，例如调用添加成员接口，添加已经在群组里的用户，或者移除聊天室中不存在的成员等操作。
• 部分操作抛出的com.easemob.group.exception.InvalidParameterException （状态码400） 异常类型替换为 com.easemob.group.exception.ForbiddenOpException (状态码403)
• 如果用户加入群组/聊天室的个数超限，或者appkey下群组/聊天室的个数超限，将抛出异常com.easemob.group.exception.ExceedLimitException， 状态码 403

相比2017-01-03第一个版本，异常及状态码有改动的接口如下：

• 群加人（单加/批量），用户已经在群里
• 群减人（单减/批量减）被减用户(存在但)都不在群
• 转让群主，自己转自己
• 转让群主，转给一个不在群里的用户
• 批量添加黑名单，用户都已经在黑名单
• 单个加入黑名单，用户不是群组成员
• 把群主加入黑名单
• 修改聊天室信息，修改的字段含有不允许修改的字段，例如id
• 聊天室减人，被删除成员不在聊天室
• 限制检查

• 旧群组抛出的异常类型：java.lang.IllegalArgumentException 状态码为400
• 新群组抛出的异常类型: com.easemob.group.exception.ResourceNotFoundException 状态码为404，异常描述为“username %s doesn't exist!”

• 旧群组服务返回200，
• 新群组服务抛出的异常类型：com.easemob.group.exception.ForbiddenOpException 状态码为403 异常描述为 “can not join this group, reason:%s”（注：批量加人时，如果部分用户不在群里，则该部分用户可以添加成功，返回状态码为200）

• 旧群组服务返回200
• 新群组服务抛出的异常类型： com.easemob.group.exception.ForbiddenOpException 状态码为403 异常描述为 “users %s are not members of this group!”（注：批量减人时，如果部分用户在群里，则该部分用户可以移除成功，返回状态码为200）

• 旧版群组服务返回200
• 新版群组服务抛出异常：com.easemob.group.exception.ForbiddenOpException 状态码403 异常描述：“new owner and old owner are the same ”

• 旧群组服务可以转成功，原来的群主被从群里移除
• 新群组服务要求新群主必须首先是群成员，因此会抛出异常 com.easemob.group.exception.ForbiddenOpException 状态码403 异常描述为：“user: %s doesn't exist in group: %s”

• 旧群组服务旧群主从群成员中移除
• 新版群组服务，旧群主还留在群里。

• 旧群服务返回200
• 新群服务抛出异常： com.easemob.group.exception.ForbiddenOpException 状态码 403 异常描述为：“users %s are not members of this group!”

• 旧群服务返回200
• 新群服务抛出异常： com.easemob.group.exception.ForbiddenOpException 状态码 403 异常描述为：“forbidden operation on group owner!”

• 旧群组抛出的异常类型：java.lang.IllegalArgumentException 状态码为400
• 新群组抛出的异常类型: com.easemob.group.exception.ResourceNotFoundException 状态码为404 异常描述为“username %s doesn't exist!”

• 旧群组服务返回200
• 新群组服务抛出的异常类型： com.easemob.group.exception.ResourceNotFoundException 状态码为404 异常描述为：“grpID %s does not exist!”

• 旧群组服务返回200
• 新群组服务抛出的异常类型： com.easemob.group.exception.ResourceNotFoundException 状态码为404 异常描述为：“grpID %s does not exist!”

• 旧群组服务返回200，修改了允许修改的内容
• 新群组服务，如果传入的修改字段中，包含不可更改，或者是无效的字段,会抛出异常： com.easemob.group.exception.InvalidParameterException 状态码为400 异常描述为 “some of %s could not be modified” 或者 “some of %s are not valid fields”
• 新群组服务，禁止通过修改群组/聊天室接口来修改owner， 否则会抛出异常:com.easemob.group.exception.ForbiddenOpException，状态码403 异常描述为： “owner cannot be updated through this method!”）

• 旧群组服务返回200
• 新群组服务抛出的异常类型： com.easemob.group.exception.ResourceNotFoundException 状态码为404 异常描述为：“grpID %s does not exist!”

• 旧群组服务返回200
• 新群组服务抛出的异常类型： com.easemob.group.exception.ResourceNotFoundException 状态码为404 异常描述：“grpID %s does not exist!”

• 旧群组抛出的异常类型：java.lang.IllegalArgumentException 状态码为400
• 新群组抛出的异常类型: com.easemob.group.exception.ResourceNotFoundException 状态码为404 异常描述： “username %s doesn't exist!”

• 旧群组服务返回200
• 新群组服务抛出的异常类型： com.easemob.group.exception.ForbiddenOpException 状态码为403 异常描述： “users %s are not members of this group!”

• 旧群组服务返回200
• 新群组服务抛出的异常类型： com.easemob.group.exception.ResourceNotFoundException 状态码为404 异常描述：“grpID %s does not exist!”

用户创建群组/聊天室，群组/聊天室加人等操作，会检查如下参数：

• 用户加入的群组个数限制
• 用户加入的聊天室个数限制
• appkey下创建群组个数的限制
• appkey下创建聊天室个数的限制

超过限制的异常：

• 旧群组服务，如果超过限制，会抛出异常： java.lang.IllegalArgumentException 状态码为400；
• 新群组服务，如果超过限制，会抛出异常：com.easemob.group.exception.ExceedLimitException 状态码为 403

新版异常描述为：

• 用户加入的群组/聊天室超过上限:“can not join this group, reason：user %s has joined too many groups/chatroom!”
• appkey下创建群组/聊天室超过上限:“this appKey has create too many groups/chatrooms!”

所有群组/聊天室的接口，如果调用者不具备相应接口的调用权限， 抛出的异常类型：com.easemob.group.exception.GroupAuthorizationException，状态码为 401