Web API 的设计风格

一直在做APP后台，顺便总结下API应该怎样去写。API的设计风格一般是遵循RESTFul设计风格的。

GET 请求遵循下面的格式。

• 请求

    1. 头信息  

Accept: application/json Content-Type: application/json;charset=utf-8 Accept-Language: <语言代码>

其中，<语言代码>取值为zh-CN、en-US、fr-FR等，可参考ISO Language Code。

对于不公开的API，需要用户认证，则还需要加上：

Authorization: Bearer <令牌>
其中，<令牌> 在调用登录API时获取，客户端需要保存该<令牌>供以后调用API时使用。

   2. 请求URL

/api/url/?filter=c1|v1,c2|v2&order=c3|asc,c4|desc&page=2&pageSize=10

其中，查询字符串(?之后的部分)由&分隔各项条件，每项条件的键值对由=分隔，包含以下部分：

filter=c1|v1,c2|v2为查询条件，多个条件用,隔开，每个条件用|隔开键值对，对应MySQL SQL查询语句的WHERE子句

order=c3|asc,c4|desc为排序，与查询条件类似，c3和c4为列，用asc和desc标明顺序或者逆序，对应MySQL SQL查询语句的ORDER BY子句

page=2和pageSize=10为分页参数，此例中就是查询第11-21条记录，对应MySQL SQL查询语句的LIMIT子句

•  响应

    响应的内容格式为：

plaintext {     "data": {         ...     },     "meta": {         "reasonCode": "<错误原因代码>",         "reason": "<错误原因描述>"     } }

 其中，各部分为：

     当API调用成功（HTTP状态代码为200）时，data就是API需要获取的数据

     当API调用失败（HTTP状态代码为4xx）时，meta包含更多的错误信息，以下为各键的含义和取值：

     reasonCode为错误原因代码，可以供客户端代码用来判断，针对不同情况做不同的处理，可能的取值为：

     VALIDATION_ERROR
     LOGIN_LICENSE_EXPIRED
     HTTP_OK
     HTTP_BAD_REQUEST
     HTTP_EXPIRED_TOKEN
     HTTP_LICENSE_EXPIRED
     HTTP_UNAUTHORIZED
     HTTP_INTERNAL_SERVER_ERROR
     其他取值有待补充

     reason为请求头信息Accept-Language中指定语言的错误原因描述，可以供客户端用来显示在用户界面中，以上错误原因代码对应的中文的可能取值为：

     数据验证错误！
     登录失败！客户端授权码已经失效。
     成功！
     非法请求！
     令牌已过期！
     客户端授权码已经失效。
     未获授权访问！
     内部服务器错误！
     其他取值有待补充