RESTful API

REST简介

REST是Representational State Transfer的缩写，REST是用来设计分布式系统的一种架构风格，其并非标准，但是是一系列的限制，例如必须是无状态的（stateless）、统一的接口。REST并非与HTTP严格绑定，但是一般都与其有联系。

• Resources expose easily understood directory structure URIs；XX表示易于理解的目录结构url；
• Representations transfer JSON or XML to represent data objects and attributes.XX传输JSON或者XML表示数据对象或者属性.表现层是资源的表现层；
• Messages use HTTP methods explicitly (for example, GET, POST, PUT, and DELETE).消息显示的使用HTTP方法
• Stateless interactions store no client context on the server between requests. State dependencies limit and restrict scalability. The client holds session state.无状态交互在请求和服务器直接不存储客户端上下文（？？），…客户端持有session状态；
• representational；具象的，即具体形象
• 以上内容相关博文连接：理解rest架构

容相关博文连接：
幂等性方法调用一次和调用多次的结果是相同的，比如get方法是对数据的读取，不论多少次结果都是相同的，因此get方法具有幂等性，但是post方法不具有；

安全性不改变资源的状态；
http方法的安全性和幂等性罗列如下，相关博文见http方法的安全性和幂等性

[注]：post创建；put更新

REST API设计规则

1. Request通过URL定位资源，推荐使用名词复数，通过http方法(GET,POST,DELETE)描述操作类型；PUT和PATCH都是在服务器更新资源，前者是客户端提供改变后的完整资源，后者是客户端提供改变的属性。
2. Response采用JSON格式，而非XML；
3. http方法符合安全性和幂等性规则；
4. 资源地址推荐使用嵌套结构：GET /friends/001/pictures 访问001号朋友的相片；
5. 返回结果较大时服务器可能不会讲所有数据返回，此时api应考虑到提供参数，过滤返回结果，如分页或者limit的形式，常用参数如下：
   
   • ?limit=10：指定返回记录的数量；
   • ?offset=10：指定返回记录的开始位置；
   • ?page=2&per_page=100;指定页数和每页显示记录数；
   • ？sortby=name&order=asc;排序依据的属性以及排序方式；
   • ？animal_type_id=1;指定筛选条件；
6. 使用正确的 HTTP Status Code表示访问状态，如404，200；
   .1XX - informational
   .2XX - success
   .3XX - redirection 重定向
   .4XX - client error，比如请求资源不存在、用户没有权限、有权限但是访问被禁止；
   .5XX - server error
7. api与客户端通信总是使用https协议；
8. 尽量使用专用域名https://api.example.com，若很简单则可考虑放在主域名下https://example.org/api/；
9. 版本号放在url中https://api.example.com/v1/；