rest api

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来唯一标识某个资源公布出来的接口。

每种HTTP请求方法都可以从安全性和幂等性两方面来考虑：安全性是指外系统对该接口的访问不会使得服务器端的资源的状态发生改变；幂等性是指外系统对同一REST接口的多次访问得到的资源状态是相同的。

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