【已转移】【Java架构：系统架构理论】一篇文章搞掂：RESTful

一、定义

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:查找信息