一、定义
1、起源
- 来源：Roy Fielding的博士论文。
- 目的：理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。
- 定义：一种实现软件通信的架构风格、设计风格，而不是标准；提供了一组设计原则和约束条件。
- 用处：提供一种架构风格，目前也有很多相关实现，我们可以理解这种风格，借助这些实现来实现一个良好通信软件架构。
2、定义
REST的名称解释：
SOAP：简单对象访问协议（英文：Simple Object Access Protocol，简称SOAP）。
REST：表述性状态传递（英文：Representational State Transfer，简称REST）。
REST是比SOAP更简单的一个Web应用可选方案。
REST是一种面向资源的架构风格，强调描述应用程序的事物和名词。
- Representational ：表述性，REST资源可以使用各种不同的形式进行表述，如XML，JSON，HTML；
- State：状态，使用REST的时候，我们关注的是资源的状态，而不是行为；
- Transfer：转移，REST的资源，通过某种形式的表述，在应用之间传递转移。
简洁地说，REST就是将资源的状态，以最合适客户端或服务器的表述方式，在服务器与客户端之间转移。
REST与HTTP方法：
URL：REST中，资源通过URL定位和识别。虽然没有严格的URL格式定义，但是一个URL应该能识别资源，而不是简单的一个命令。因为REST的核心是资源，而不是行为。
行为：REST中也有行为，但是不是在URL中体现，一般通过HTTP行为来定义，例如CRUD
- Creat:POST
- Read:GET
- Update:PUT/PATCH
- Delete:Delete
最佳实践
RESTful API的设计实践
可以参考这篇文章，翻译得很好：https://www.cnblogs.com/moonz-wu/p/4211626.html
也可以参考这个网站的API介绍：https://onlinehelp.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm
我的总结：
1、动词的使用场景
- GET(选择)：从服务器上获取一个具体的资源或者一个资源列表。
- POST(创建)： 在服务器上创建一个新的资源。
- PUT(更新)：以整体的方式更新服务器上的一个资源。
- PATCH(更新)：只更新服务器上一个资源的一个属性。
- DELETE(删除)：删除服务器上的一个资源
2、使用api根和版本管理
- https://example.org/api/v1/*
- https://api.example.com/v1/*
3、使用复数代表集合
- www.xx.com/api/v1/products
4、使用小写和-分隔符
- www.xx.com/api/v1/product-types
5、使用过滤器传递参数
- ?sort-by=name&order=asc
6、同级数据使用...进行分割
- www.xx.com/api/v1/compare/a...b...c
实际应用：
- 增加商品[POST]/api/v1/products/p-id
- 修改商品[PUT]/api/v1/products/p-id
- 删除商品[DELETE]/api/v1/products/p-id
- 审核商品[POST]/api/v1/products/p-id/post
- 反审核商品[DELETE]/api/v1/products/p-id/post
- 失效商品[POST]/api/v1/products/p-id/cancel
- 查询商品（使用ID）[GET]/api/v1/products/p-id
- 查询商品（使用编码）[GET]/api/v1/products/p-id?code=编号
- 商品列表（分页，参数）[GET]/api/v1/products?page-no=1&page-size=10&sort=code:asc,name:desc,qty:asc&filter=name:eq:名称条件,code:eq:名称条件
- 商品列表（分页，参数，给APP使用）[GET]/api/v1/products?type=app&page-no=1&page-size=10&sort=code:asc,name:desc,qty:asc&search:eq:查找信息