新版群组/聊天室服务 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!”

聊天室服务

聊天室信息维护

创建聊天室,聊天室成员不存在,旧群组服务返回400,新群组服务返回404

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

删除聊天室,聊天室id不存在

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

修改聊天室信息,聊天室id不存在

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

修改聊天室信息,修改的字段含有不允许修改的字段,例如id

  • 旧群组服务返回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!”

聊天室减人(单减/批量减),聊天室id不存在

  • 旧群组服务返回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