RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计，它的大原则容易把握，但是细节不容易做对。本文总结 RESTful 的设计细节，当我们在设计API时如果不遵循这些细节也不会报错，但是不是很符合Restful设计规范。
1、URL 设计
动词 + 宾语
RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /articles这个命令，GET是动词，/articles是宾语。这里提到的“动词”就是Http方法
- GET：读取（Read）
- POST：新建（Create）
- PUT：更新（Update）
- PATCH：更新（Update），通常是部分更新
- DELETE：删除（Delete）
宾语必须是名词
宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词（建议是名词的复数），不能是动词。比如，/articles这个 URL 就是正确的，而下面的 URL 不是名词，所以都是错误的。
- /getAllCars
- /createNewCar
另：在设计url时尽量避免多级URL，尽可能的只保留一级其他的都使用参数
// 多级URL
GET /authors/12/categories/2
//参数化
GET /authors/12?categories=2
2、状态码
状态码分类
客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分且状态码要精确，因为不同的状态码代表不同的含义。以下为状态码的大体分类
- 1xx：相关信息
- 2xx：操作成功
- 3xx：重定向
- 4xx：客户端错误
- 5xx：服务器错误
API 不需要1xx状态码
2xx状态码
200状态码表示操作成功，但是不同的方法可以返回更精确的状态码。
- GET: 200 OK
- POST: 201 Created.
- PUT: 200 OK
- PATCH: 200 OK
- DELETE: 204 No Content
上面代码中，POST返回201状态码，表示生成了新的资源；DELETE返回204状态码，表示资源已经不存在，此外，202 Accepted状态码表示服务器已经收到请求，但还未进行处理，会在未来再处理，通常用于异步操作。
3xx状态码
API 用不到301状态码（永久重定向）和302状态码（暂时重定向，307也是这个含义），因为它们可以由应用级别返回，浏览器会直接跳转，API 级别可以不考虑这两种情况。
API 用到的3xx状态码，主要是303 See Other，表示参考另一个URL。它与302和307的含义一样，也是"暂时重定向"，区别在于302和307用于GET请求，而303用于POST、PUT和DELETE请求。收到303以后，浏览器不会自动跳转，而会让用户自己决定下一步怎么办。
4xx状态码
4xx状态码表示客户端错误，主要有下面几种
- 400 Bad Request：服务器不理解客户端的请求，未做任何处理。
- 401 Unauthorized：用户未提供身份验证凭据，或者没有通过身份验证
- 403 Forbidden：用户通过了身份验证，但是不具有访问资源所需的权限
- 404 Not Found：所请求的资源不存在，或不可用
- 405 Method Not Allowed：用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限之内
- 410 Gone：所请求的资源已从这个地址转移，不再可用
- 415 Unsupported Media Type：客户端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客户端要求返回 XML 格式
- 422 Unprocessable Entity ：客户端上传的附件无法处理，导致请求失败
- 429 Too Many Requests：客户端的请求次数超过限额
5xx状态码
5xx状态码表示服务端错误, 主要有下面几种
- 500 Internal Server Error：客户端请求有效，服务器处理时发生了意外
- 503 Service Unavailable：服务器无法处理请求，一般用于网站维护状态
3、服务器回应
API 返回的数据格式，不应该是纯文本，而应该是一个 JSON 对象，因为这样才能返回标准的结构化数据。所以，服务器回应的 HTTP 头的Content-Type属性要设为application/json。
客户端请求时，也要明确告诉服务器，可以接受 JSON 格式，即请求的 HTTP 头的ACCEPT属性也要设成application/json。下面是一个例子。
Accept: application/json
网友评论