基本规定

请求尽量采用rest风格

1.请求地址

(https配置已完并强制采用)

api请求地址前缀在测试期间为:

    https://api.samaritan.tech

接口示例中不再重复书写,即:

    /students/123

实际代表:

    https://api.samaritan.tech/students/123

2.请求权限

low：任意访问

medium：登录访问

2.请求内容

a. 双方以json传输(GET方法除外),字段参考对象属性;

b. client需设置Accept为application/json;

c. client在登陆成功后,会获取到服务器返回的token值, 请将header中的Authorization设置为该值,否则无权操作需要授权的接口;

3.请求方法

基本对应关系:

• POST

POST方法用于向server申请创建内容

示例:

学生注册

    POST /students

• GET

GET方法用于向server请求内容

示例:

a.请求id为123学生的信息

    GET /students/123

b. 请求所有课程的信息,限制为10条

    GET /courses?limit=10

• PUT

PUT方法用于向server申请更新内容

示例:

更新id为123的学生手机号

    PUT /students/123/phone

• DELETE

PUT方法用于向server申请删除内容

示例:

删除id为123的学生

    DELETE /students/123

4.返回内容

请求默认以http status code来标志请求状态

200: 请求成功执行

400: 请求格式错误,详情查看msg字段

401: 未授权请求,查看请求header中Authorization字段

403: 请求禁止,用户信息与授权信息不匹配

500: 服务器错误,客户端通知服务器解决

其次，所有失败的请求都会返回错误信息

    {
        code: 400/401...,
        msg 错误描述...
    }

code为错误状态码，为0时表示无错误; msg为错误描述信息

注意：请求成功时，msg字段会省略。

即：

请求成功，返回

    {
        code: 0,
        key: value,
        foo: bar    
    }

请求失败，返回

    {   
        code: 400,
        msg: "错误描述"
    }