Restful Api 接口风格，最佳实践设计

RESTful API的开发和使用，无非是客户端向服务器发请求（request），以及服务器对客户端请求的响应（response）。具备统一接口的特色，即，使用不一样的http方法表达不一样的行为：

• GET（SELECT）：从服务器取出资源（一项或多项）
• POST（CREATE）：在服务器新建一个资源
• PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）
• PATCH（UPDATE）：在服务器更新资源（客户端提供须要修改的资源数据）
• DELETE（DELETE）：从服务器删除资源
• GET /tickets # 获取ticket列表
• GET /tickets/12 # 查看某个具体的ticket
• POST /tickets # 新建一个ticket
• PUT /tickets/12 # 更新ticket 12.
• DELETE /tickets/12 #删除ticekt 12

经常使用的Response要包含的数据和状态码（status code），不完善的内容，欢迎你们补充:

• 当GET, PUT和PATCH请求成功时，要返回对应的数据，及状态码200，即SUCCESS
• 当POST建立数据成功时，要返回建立的数据，及状态码201，即CREATED
• 当DELETE删除数据成功时，不返回数据，状态码要返回204，即NO CONTENT
• 当GET 不到数据时，状态码要返回404，即NOT FOUND
• 任什么时候候，若是请求有问题，如校验请求数据时发现错误，要返回状态码 400，即BAD REQUEST
• 当API 请求须要用户认证时，若是request中的认证信息不正确，要返回状态码 401，即NOT AUTHORIZED
• 当API 请求须要验证用户权限时，若是当前用户无相应权限，要返回状态码 403，即FORBIDDEN

 最后，关于Request 和 Response，不要忽略了http header中的Content-Type。以json为例，若是API要求客户端发送request时要传入json数据，则服务器端仅作好json数据的获取和解析便可，但若是服务端支持多种类型数据的传入，如同时支持json和form-data，则要根据客户端发送请求时header中的Content-Type，对不一样类型是数据分别实现获取和解析；若是API响应客户端请求后，须要返回json数据，须要在header中添加Content-Type=application/json。

使用方式

GET http://www.birjemin.com/api/user # 获取列表

POST http://www.birjemin.com/api/user # 建立用户

PUT http://www.birjemin.com/api/user/{id} # 修改用户信息

DELETE http://www.birjemin.com/api/user/{id} # 删除用户信息

设计要素

• 资源路径： /users , /articles
• HTTP动词： GET,POST,DELETE,PUT
• 过滤信息： 文章分页筛选
• 状态码： 200，404，422，403…
• 错误处理：输出JSON格式错误信息
• 返回结果：输出JSON数组或JSON对象
• version，必须向前兼容，版本号可放入head（有时把版本号放在URL里要比放在请求的首部中更容易实现和使用）

 

速度限制
若是对访问的次数不加控制，极可能会形成 API 被滥用，甚至被 DDos 攻击。根据使用者不一样的身份对其进行限流，能够防止这些状况，减小服务器的压力。为此 RFC 6585 引入了HTTP状态码429（too many requests）。加入速度设置以后，应该提示用户，至于如何提示标准上没有说明，不过流行的方法是使用HTTP的返回头。

对用户的请求限流以后，要有方法告诉用户它的请求使用状况，Github API 使用的三个相关的头部：

X-RateLimit-Limit: 用户每一个小时容许发送请求的最大值
X-RateLimit-Remaining：当前时间窗口剩下的可用请求数目
X-RateLimit-Rest: 时间窗口重置的时候，到这个时间点可用的请求数量就会变成X-RateLimit-Limit的值
若是容许没有登陆的用户使用 API（可让用户试用），能够把 X-RateLimit-Limit 的值设置得很小，好比 Github 使用的 60。没有登陆的用户是按照请求的 IP 来肯定的，而登陆的用户按照认证后的信息来肯定身份。

对于超过流量的请求，能够返回429 Too many requests状态码，并附带错误信息。而 Github API 返回的是403 Forbidden，虽然没有 429 更准确，也是能够理解的。

宗旨：

漂亮、简洁、优雅