REST(Representational State Transfer, 表述性状态转移)，源于Roy Thomas Fielding博士在2000年在校期间发表的一篇学术论文《Architectural Styles and the Design of Network-based Software Architectures》。从题目中也可以看出来REST是一种架构风格，不是一种协议或者技术。
RESTful API 翻译过来就是REST式的API就是满足REST这种风格的API。具有跨平台、跨语言的优势，并且实现简洁直观。近来越来越受开发者喜欢，特别是最近微服务化的火热又推动了一把REST的使用。
特点
论文中提出了REST的6个特点：
- 客户端-服务器的
- 无状态的
- 可缓存的
- 统一接口
- 分层系统
- 按需编码
这6个特点具体所指可以看下论文原文，或者可以看下这个连接。
REST实现方式
基于即有的HTTP/HTTPS + URI + XML/JSON实现。在REST架构风格中，对象被抽象成一种资源（使用清晰的名词来定义）。
REST的资源是通过HTTP协议定义的动词（GET/PUT/POST/DELETE等）来操作，并使用URI来唯一标识某个资源公布出来的接口。
每种HTTP请求方法都可以从安全性和幂等性两方面来考虑：安全性是指外系统对该接口的访问不会使得服务器端的资源的状态发生改变；幂等性是指外系统对同一REST接口的多次访问得到的资源状态是相同的。
- GET/HEAD/OPTIONS三个方法即是安全的又是幂等的
- PUT/DELETE方法是幂等的，但是不安全的，因为PUT是一种写操作
- POST既不幂等也不安全
PUT和POST是争议性最大的两个方法，作用比较接近，一般来说使用PUT来更新数据，而使用POST来添加数据
当然这只是REST中对这些HTTP方法赋予的规范性，并没有要求用户必须这样实现，但如果按照这种规范性来实现会使用接口变得更通用，更易于理解维护。
REST资源定位
REST使用URI实现资源定位，即对外提供的接口就是一系列的URI及其参数。
在设计RESTful API时资源地址的设计一定要非常严谨，如果设计不好不仅REST接口的风格无法统一，系统的扩展性和易用性也会大打折扣。
好的RESTful API中，资源名称应是准确描述该资源的名词，资源地址应该具有直观的描述性。例如小区/楼号/楼层/房屋号。
注意：在复杂的现实情况中是有很多情况是路径变量难以准备描述的，可以考虑使用动词做为查询参数来解决。
资源地址
一个典型的URI包括协议名称、主机名、服务端口、资源地址和查询字符串5部分组成。
schema://host:port/path?queryString
| 组成 | 说明 |
|---|---|
| schema | 协议名称。一般是HTTP/HTTPS |
| host | 主机名，可以是域名或者ip |
| port | 端口号 |
| path | 资源地址, 使用/分隔逻辑上的层次结构 |
| ？ | 分隔资源地址和查询字符串，如果没有查询字符串，？可省略 |
| queryString | 查询字符串，key=value形式，如果有多个可以使用&连接 |
其中path就是资源地址，一般使用basepath和pathinfo来细分；例如很有名的OpenAPI规范swagger。另外在web服务中basepath又被细分为contextpath和servletpath。
注意：资源地址是需要与HTTP方法结合一起来定位具体资源。资源地址相同HTTP方法不同两个方法是对应两个不同的REST接口的。例如
GET /books/<id>和PUT /books/<id>
常用于资源URI中的标点符号
为了增加逻辑的清晰性，在路径变量中提供了几个常用的标点符号：
-
?(问号)：用来分隔资源地址和查询字符串，这个上一节有说明。 -
&(与)：用来分隔多个查询条件的参数，这个上一节有说明。 -
,(逗号)：用来分隔逻辑上有次序的作用域信息，使用"月,日,年" -
-(连接符)：可以做为逻辑上的辅助分隔，例如2012-2018表示2012年到2018年。 -
_(下划线)：一般用于多个单词的连接成一个完整的字段，例如book_type_id=1 -
;(分号)：用来分隔无次序的作用域信息，例如并列查询条件。
常用的资源地址示例：
| 功能 | 资源地址 |
|---|---|
| 添加/创建 | POST /books |
PUT /books/{id} |
|
| 删除 | DELETE /books/{id} |
| 修改/更新 | PUT /books/{id} |
| 查询全部 | GET /books |
| 主键查询 | GET /books/{id} |
GET /books?id=12345 |
|
| 分页作用域查询 | GET /books?start=0&size=10 |
GET /books/01,2012-12,2014 |
|
GET /books/restful;program=java;type=web |
|
GET /books?limit=100&sort=bookname |
API接口版本
任何人设计的有用的功能都是要向前演进的，不可能一成不变。一般是引入版本号的概念来解决这种演进的问题。而RESTful API的版本号可以通过以下几种方式实现：
- 在uri中放版本信息：GET /v1/users/1
- Accept Header：Accept: application/json+v1
- 自定义 Header：X-Api-Version: 1
通常建议使用第一种方式，简单直观。
其他
- RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么
- 请求以及返回数据使用JSON格式，不要使用XML格式
- 返回出错信息时，数据key统一起来，使用使用
ERROR，而错误信息作为value
