RestfulAPI接口设计指导

1.简介

互联网的兴起，研究者思考如何开发以网络为基础的软件。Fielding提出了解决这个问题的软件架构原则:REST(Representational State Transfer),表现层状态转化。符合REST原则的架构，被称为RESTful架构，是目前互联网最流行的一种软件架构。REST的主语是Resource,即资源的表现层转化。
资源:是网络上的具体信息，可以是文本、图片、歌曲、服务等，使用URI指向它，一般也把资源称为对象。
表现层:是资源的一种表现形式，比如文本可以使用txt、html、xml、json等格式表现出来，表现层在Http请求头中Accept和Context-Type指定。
状态转化:客户端与服务端交互，必然会使资源发生变化，因为Http是无状态协议，所以资源的状态一定保存在服务端。所以客户端想改变资源状态，只能通过某种手段，使服务端的资源状态发生变化。这种手段就是HTTP协议，HTTP协议主要有四类动词:GET用来获取资源，POST用来新建资源，PUT用来更新资源，DELETE用来删除资源。由于这种状态转化是基于表现层，所以称为表现层状态转化。

1.1 restful架构的特点

1.一个URI代表一个资源
2.客户端和服务器之间，传递这种资源的某个表现层
3.客户端通过四个HTTP动词，对服务器端资源进行操作，实现“表现层状态转换”

2. Restful接口设计

因为Restful架构主要关注资源、对资源的操作。所以Restful API主要是关注URI、操作方法的设计。

2.1 URI设计

该设计的目的是让整个接口更具自描述性，这样在接口的易用性和可维护性上有更好的表现。
Restful API资源URI一般由两个部分组成:
Path和Query Parameters

2.1.1 Path

主要描述一个资源的访问路径，Path一般由名词组成
面对不同场景，Path的设计有不同的实践方式，下面是常见的实践方法:
1.资源对象集
2.单个资源对象
3.资源从属关系
4.资源索引关系

2.1.2 Query Parameters

Query Parameter是URI中问号？之后出现的key value参数。在restful api设计中，提供的是一个可选参数作用:不使用该参数，不影响API的执行。

2.1.3 方法设计

在Restful API中，对于资源的操作方法，最常用的是POST、PUT、GET和DELETE。
http官方协议规格说明中PUT、GET和DELETE是幂等的，而POST不是。
GET: 使用？增加可选查询参数，规范上没有请求体
PUT:请求体，规范上不使用？增加可选参数
DELETE:请求体，规范上不使用？增加可选参数
POST:请求体，规范上不使用？增加可选参数

2.1.4 版本

API中一定要有版本管理，便于维护，让系统更加容易进行升级重构

2.1.5 状态码

2xx 成功 一切正常
3xx 重定向
4xx 客户端错误
5xx 服务器错误

2.2 优秀API特点

自解释

一眼看懂API干了什么，支持的用法，适用的场景

易学习

有完善的文档，提供尽可能多的示例和可copy paste的代码

易使用

功能强大，使用简单。调用方只做最小的感知和最少传参

难误用

优秀的API让有经验的开发直接使用，不需要阅读文档。有效的错误提示、显性的异常说明