API 接口管理规范

一、跨域问题

由于浏览器的同源策略，WEB API开发搜先要解决的就是跨越问题。在跨域的解决方案中，推荐CORS，不建议使用JSONP。

二、请求（json）

1. 统一使用POST请求

2. 请求头：

Content-Type:application/json

3. 请求body格式：

{
    "token":"fc5af216-6b44-4f93-89eb-e4328e565b1c",  // 鉴权标识，没有可不填
    "data":{                                         // 参数集
        "id":"1094"
    }
}

4. 不建议在header里放参数。

三. 返回格式（json）：

{
    "code" : 1,                         // 状态码，其他为错误代码
    "time" : "1561361175",              // 时间戳
    "msg" : "操作成功",                 // 提示消息
    "data" : []                        // 返回数据
}

四. 接口状态码：

公共服务

其他由自身业务自定服务，如：

五. HTTP状态码：

为每一次的响应返回合适的HTTP状态码。 好的响应应该使用如下的状态码:

• 200: GET请求成功，及DELETE或PATCH同步请求完成，或者PUT同步更新一个已存在的资源
• 201: POST 同步请求完成，或者PUT同步创建一个新的资源
• 202: POST，PUT，DELETE，或PATCH请求接收，将被异步处理
• 206: GET 请求成功，但是只返回一部分

使用身份认证（authentication）和授权（authorization）错误码时需要注意：

• 401 Unauthorized: 用户未认证，请求失败
• 403 Forbidden: 用户无权限访问该资源，请求失败

当用户请求错误时，提供合适的状态码可以提供额外的信息：

• 422 Unprocessable Entity: 请求被服务器正确解析，但是包含无效字段
• 429 Too Many Requests: 因为访问频繁，你已经被限制访问，稍后重试
• 500 Internal Server Error: 服务器错误，确认状态并报告问题

对于用户错误和服务器错误情况状态码，参考： HTTP response code spec