restful API

出现原因

    前后端分离之后，后端负责数据编造，前端负责数据渲染，前端通过调用指定API获取统一格式的静态数据，之内的API的设计就成为了一个问题，
    restful API就是其中一种便于理解，易于使用的一种api约束。

设计原则

1 客户端-服务器：通过将用户UI与数据存储分开，我们可以简化服务器组件来提高跨多个平台的用户界面的可移植性并提高可伸缩性。 它可以比表>现成前后端分离的思想。
2 无状态：从客户端到服务器的每个请求都必须包含理解请求所需的所有信息，并且不能利用服务器上任何存储的上下文。 这表示你应该尽可能的避免使用session，由客户端自己标识会话状态。（token）
3 规范接口：REST接口约束定义：资源识别; 请求动作; 响应信息; 它表示通过uri标出你要操作的资源，通过请求动作（http method）标识要执行的操作，通过返回的状态码来表示这次请求的执行结果。
4 可缓存： 缓存约束要求将对请求的响应中的数据隐式或显式标记为可缓存或不可缓存。如果响应是可缓存的，则客户端缓存有权重用该响应数据以用于以后的等效请求。 它表示get请求响应头中应该表示有是否可缓存的头（Cache-Control)
其中1，2，3约束最为重要，其中1容易理解。接下来我们就谈谈无状态和规范接口的原则。
链接：https://www.jianshu.com/p/a35bad7dbc54

URI规范 （统一资源定位符，URL：统一资源标识符）

uri是具体的资源，而url是具体的资源的地址，url是属于uri的一部分
资源描述构成了URI,其约束一般如下

1. 使用名词。如user，student
   http://api.example.com/class-management/students
   http://api.example.com/user-management/users/
   http://api.example.com/user-management/users/{id}
2. http method对应不同的请求动作（数据库或业务)

• GET---查询操作
  HTTP GET /devices?startIndex=0&size=20
  HTTP GET /configurations?startIndex=0&size=20 （url传参可用？连接，多个参数用&连接）
• POST---新增操作
  HTTP POST /device
• PUT---更新操作
  HTTP PUT /devices/{id}
• PATCH---部分更新，由于浏览器兼容性问题，更推荐put
  HTTP PATCH /devices/{id}
• DELETE---删除操作

3. 使用连字符（-）而不是（_)来提高URI的可读性
   http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //更易读
4. 在URI中使用小写字母
   http://api.example.org/my-folder/my-doc
5. 不推荐使用文件扩展名
   http://api.example.com/device-management/managed-devices.xml （错误写法）
   http://api.example.com/device-management/managed-devices （正确写法）
6. 使用查询组件过滤URI集合
   很多时候需要对数据进行排序，搜索和过滤的操作，建议的写法是将输入参数作为查询参数，为不是创建新的API
   

http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ

7. 不要在末尾使用/
   作为URI路径中的最后一个字符，正斜杠（/）不会添加语义值，并可能导致混淆。最好完全放弃它们。
8. 使用http状态码定义api执行结果
   1xx：信息
   通信传输协议级信息。
   2xx：成功
   表示客户端的请求已成功接受
   3xx：重定向
   表示客户端必须执行一些其他操作才能完成其请求。
   4xx：客户端错误
   此类错误状态代码指向客户端。
   5xx：服务器错误
   服务器负责这些错误状态代码。
   如前端调用接口经常用到的400，是客户端的错误，一般是传参不对或者格式有问题
   500 就是服务器错误，无法完成请求
9. api版本定义
   已经有投入使用的api,此时api更新升级，此时可以使用下面的方法

• 版本控制(推荐）
  http://api.example.com/v1
• 使用自定义请求标头进行版本控制
  Accept-version：v1

无状态

1. 无状态通过将api部署到多个服务器中，有助于扩展到数百万并发用户。（集群）
2. 无状态使得REST API不那么复杂 - 可以删除所有服务器端状态同步逻辑。（删除session，清理多余空间）
3. 无状态API也很容易缓存。特定软件可以通过查看该一个请求来决定是否缓存HTTP请求的结果。（易缓存）
4. 客户端会在每个请求中发送所有必要的信息，如服务器存贮的token等。（携带token）

部分信息转载至https://www.jianshu.com/p/a35bad7dbc54