rest api
REST(Representational State Transfer, 表述性状态转移)。
REST是一种架构风格，不是一种协议或者技术。
RESTful API 翻译过来就是REST式的API就是满足REST这种风格的API。具有跨平台、跨语言的优势，并且实现简洁直观。近来越来越受开发者喜欢，特别是最近微服务化的火热又推动了一把REST的使用。
REST实现方式
基于即有的HTTP/HTTPS + URI + XML/JSON实现。在REST架构风格中，对象被抽象成一种资源（使用清晰的名词来定义）。
REST的资源是通过HTTP协议定义的动词（GET/PUT/POST/DELETE等）来操作，并使用URI来唯一标识某个资源公布出来的接口。
REST资源定位
REST使用URI实现资源定位，即对外提供的接口就是一系列的URI及其参数。
在设计RESTful API时资源地址的设计一定要非常严谨，如果设计不好不仅REST接口的风格无法统一，系统的扩展性和易用性也会大打折扣。
资源地址
一个典型的URI包括协议名称、主机名、服务端口、资源地址和查询字符串5部分组成。
schema://host:port/path?queryString
| 组成 | 说明 |
|---|---|
| schema | 协议名称。一般是HTTP/HTTPS |
| host | 主机名，可以是域名或者ip |
| port | 端口号 |
| path | 资源地址, 使用/分隔逻辑上的层次结构 |
| ？ | 分隔资源地址和查询字符串，如果没有查询字符串，？可省略 |
| queryString | 查询字符串，key=value形式，如果有多个可以使用&连接 |
常用于资源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