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

新版群组/聊天室服务 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
•  聊天室减人，被删除成员不在聊天室
•  限制检查

 ------------------------------------------------------------------------------------------------------------ 1.群组服务成员操作群加人（单加/批量），用户不存在

• 旧群组抛出的异常类型：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!"

2.聊天室服务聊天室信息维护创建聊天室，聊天室成员不存在，旧群组服务返回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!"

限制检查用户创建群组/聊天室，群组/聊天室加人等操作，会检查如下参数[list=1]用户加入的群组个数限制用户加入的聊天室个数限制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