3.接口文档

接口文档

HTTP部分
Socket自定义协议

Http部分

（一般都是这样）

全局规范

URL
URL的组成：基本的网络地址 ＋ 分支节点
http://127.0.0.1:8080/chat 为 基本的网络地址
/login 为 分支节点
http://127.0.0.1:8080/chat/login 组成完整的 URL
当前统一的基本网络地址为 http://127.0.0.1:8080/ChatServer
请求方式
POST
GET
PUT
请求消息头
键值对(key value形式)
请求参数
键值对(key value形式)
响应的状态码
统一的返回码为: 200 (注:只要访问服务器成功，一律返回200)
响应的格式
Json
响应的JSON规范
- 成功
  {flag:true, data:...}
  成功的标记为 flag 为 true
  根据具体的请求，如果需要返回值 data节点 包含的是 返回结果
  不需要需要返回值，则没有data节点
- 失败
  {flag:false, errorCode:1, errorString:"错误原因"} 失败的标记为 flag 为 false
  flag 为 false时，必然返回 errorCode和errorString 节点
  errorCode说明了错误编码
  errorString说明错误原因

Login(登录接口)

分支节点 : /login
请求方式 : POST
请求参数 :
key | 类型 | 说明 ------------ | -------- | ------------ account | String | 用户的账号 password | String | 用户的密码

响应结果 :

成功

{
    "flag": true,
    "data": {
        "account": "zhangsan",
        "name": "张三",
        "sex": 1,
        "icon": "/a/b/zhangsan.png",
        "sign": "我的个性签名",
        "area": "深圳",
        "token": "5904c7ae-3e75-48c8-bbee-ad094533a422"
    }
}

失败
errorCode | errorString ---------- | -------------- 100 | 用户密码错误 101 | 用户不存在

Regisger(注册接口)

分支节点 : /register
请求方式 : POST
请求参数 :
key | 类型 | 说明 ------------ | -------- | ------------ account | String | 用户注册的账号 password | String | 用户注册的密码

响应结果 :

成功

{
    "flag": true,
    "data": {
        "account": "zhangsan",
        "name": "张三",
        "sex": 1,
        "icon": "/a/b/zhangsan.png",
        "sign": "我的个性签名",
        "area": "深圳",
        "token": "5904c7ae-3e75-48c8-bbee-ad094533a422"
    }
}

失败
errorCode | errorString ---------- | -------------- 150 | 用户已经存在

搜索用户接口

分支节点 : /user/search
请求方式 : POST
请求消息头 :
```
key      | 类型      | 说明
```
------------ | -------- | ------------ account | String | 用户的账号 token | String | 用户的唯一标识
请求参数 :
```
key      | 类型      | 说明
```
------------ | -------- | ------------ search | String | 搜索的账号

响应结果 :

成功

{
    "flag": true,
    "data": {
        "account": "zhangsan",
        "name": "张三",
        "icon": "/a/b/zhangsan.png",
        "sign": "我的个性签名",
        "area": "深圳"
    }
}

失败
errorCode | errorString ---------- | -------------- 200 | 用户不存在

接受用户用户邀请

分支节点 : /friend/accept
请求方式 : POST
请求消息头 :
```
key      | 类型      | 说明
```
------------ | -------- | ------------ account | String | 用户的账号 token | String | 用户的唯一标识
请求参数 :
key | 类型 | 说明 ------------ | -------- | ------------ invitor | String | 邀请者的账号 acceptor | String | 接受者的账号

响应结果 :

成功
```
{
    "flag": true
}       
```
失败
```
{
    "flag": false
}       
```

获取朋友列表

分支节点 : /friend/list
请求方式 : POST
请求消息头 :
```
key      | 类型      | 说明
```
------------ | -------- | ------------ account | String | 用户的账号 token | String | 用户的唯一标识
请求参数 : 无

响应结果 :

成功
```
{
    "flag": true
}       
```
失败
```
{
    "flag": false
}       
```

用户名称修改接口

分支节点 : /user/nameChange
请求方式 : POST
请求消息头 :
```
key      | 类型      | 说明
```
------------ | -------- | ------------ account | String | 用户的账号 token | String | 用户的唯一标识
请求参数 :
```
key      | 类型      | 说明
```
------------ | -------- | ------------ name | String | 修改后的用户名

响应结果 :

成功
```
{
    "flag": true
}       
```
失败
```
{
    "flag": false
}       
```

Sokect自定义协议

全局规范

协议的定义
1. 传输格式为json
2. 协议分为 请求 和 响应
3. 传输方向:
  client --> server : 发送消息
  server --> client : 推送消息
4. 发送消息
  发送过程包含的两个过程：
  请求 : client 发送消息到 server
  响应 : server 响应 client 的这次消息请求
  两个过程都完成才算当前消息发送成功
5. 推送消息
  推送过程包含的两个过程：
  请求 : server 发送消息到 client
  响应 : client 响应 server 的这次消息请求
  两个过程都完成才算当前消息发送成功
6. 消息必备格式
  请求部分:
```
{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "request",
    "action": "text"
}
```
  响应部分:
```
{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "true"
}       
```
  sequece : 标记请求和响应，用来表明 响应 是针对哪次 请求的
  type : 用来标记是 请求 还是 响应
  action : 请求发送方的发送类型，由具体请求决定取值。

Client 部分

Auth认证

Action : auth
请求的 key-Value
key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:auth sender | String |发送者账号 token | String |发送者token标志

请求的json 格式:

{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "request",
    "action": "auth",
    "sender":"xxxx",
    "token":"xxxx"
}

{"sequence":"1","type":"request","action":"auth","sender":"iphone1","token":"0dce6f76ac1a29d276c0c6dabe60519c"}

响应的json 格式:

成功 :

{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "true",
}

失败 :

{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

发送邀请

Action : invitation
请求的 key-Value
key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:invitation sender | String |发送者账号 token | String |发送者token标志 receiver| String |接收者的账号 content | String |邀请的文本内容

请求的json 格式:

{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "request",
    "action": "invitation",
    "token":"xxxx",
    "sender":"xxxx",
    "receiver":"xxxx",    
    "content":"xxxxxx"
}

响应的json 格式:

成功 :

{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "true",
}

失败 :

{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

发送文本消息

Action : text
请求的 key-Value
key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:invitation sender | String |发送者账号 token | String |发送者token标志 receiver| String |接收者的账号 content | String |邀请的文本内容

请求的json 格式:

{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "request",
    "action": "text",
    "token":"xxxx",
    "sender":"xxxx",
    "receiver":"xxxx",    
    "content":"xxxxxx"
}

响应的json 格式:

成功 :

{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "true",
}

失败 :

{
    "sequence": "9f4c696e-9ab5-46cf-959c-b1e2e35200d2",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

Server 部分

推送用户邀请

action : invitation
请求的 key-Value
key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:invitation sender | String |发送者账号 receiver| String |接收者的账号 invitorname|String |邀请者的名字 invitoricon|String |邀请者的头像 content | String |邀请的文本内容

请求的json 格式:

{
    "sequence":"3",
    "type":"request",
    "action":"invitation",
    "sender":"iphone1",
    "receiver":"iphone2",
    "invitor_name":"iphone2",
    "invitor_icon":"/icon/iphone2.png",
    "content":"hehe"
}

响应的json 格式:

成功 :

{
    "sequence": "3",
    "type": "response",
    "flag": "true",
}

失败 :

{
    "sequence": "3",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

推送用户接受邀请

action : reinvitation
请求的 key-Value
key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:reinvitation sender | String |发送者账号 receiver| String |接收者的账号 name | String |接受邀请者的名字 icon | String |接受邀请者的头像 content | String |邀请的文本内容

请求的json 格式:

{
    "sequence":"3",
    "type":"request",
    "action":"text",
    "sender":"iphone1",
    "receiver":"iphone2",
    "name":"iphone1",
    "icon","/icon/iphone1.png",
    "content":"hehe"
}

响应的json 格式:

成功 :

{
    "sequence": "3",
    "type": "response",
    "flag": "true",
}

失败 :

{
    "sequence": "3",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

推送文本消息

action : text
请求的 key-Value
key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:text sender | String |发送者账号 receiver| String |接收者的账号 content | String |邀请的文本内容

请求的json 格式:

{
    "sequence":"3",
    "type":"request",
    "action":"text",
    "sender":"iphone1",
    "receiver":"iphone2",
    "content":"hehe"
}

响应的json 格式:

成功 :

{
    "sequence": "3",
    "type": "response",
    "flag": "true",
}

失败 :

{
    "sequence": "3",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

推送用户名变更

action : nameChange
请求的 key-Value
key | 类型 | 说明 --------|-----------|------------- type | String |请求：request sequence| String |请求的序列号 action | String |请求的行为:nameChange sender | String |发送者账号 receiver| String |接收者的账号 name | String |发送者变更后的名字

请求的json 格式:

{
    "sequence":"3",
    "type":"request",
    "action":"text",
    "sender":"iphone1",
    "receiver":"iphone2",
    "content":"hehe"
}

响应的json 格式:

成功 :

{
    "sequence": "3",
    "type": "response",
    "flag": "true",
}

失败 :

{
    "sequence": "3",
    "type": "response",
    "flag": "false",
    "errorCode":"",
    "errorString":""
}

附件列表

posted @ 2016-02-13 17:26 梦和远方阅读(239) 评论(0) 收藏举报

刷新页面返回顶部

六月的雨

3.接口文档

接口文档

Http部分

（一般都是这样）

全局规范

Login(登录接口)

Regisger(注册接口)

搜索用户接口

接受用户用户邀请

获取朋友列表

用户名称修改接口

Sokect自定义协议

全局规范

Client 部分

Auth认证

发送邀请

发送文本消息

Server 部分

推送用户邀请

推送用户接受邀请

推送文本消息

推送用户名变更

附件列表