如何设计规范的RESTful API

前言

哈喽，大家好，我是asong。最近比较忙，鸽了好久的文章，表示抱歉。今天，我又来做知识分享了。

我们平常在做Web开发时，需要做数据接口的设计。RESTful是目前最流行的API设计规范，它的最大原则容易把握，但是细节不容易做对。所以本文对RESTful进行设计介绍，方便大家的理解与使用。

01

URL

RESTful的核心思想就是，把客户端发出的数据+操作执行都都当作是“动词+宾语”的结构，比如GET/data命令，GET就是动词，/data就是宾语，动词通常就有5种HTTP请求方法，对应CRUD操作，根据HTTP规范，动词需要大写。

1. GET ：获取（Read）
2. POST：新建 （Create）
3. PUT：更新（Update）
4. PATCH：更新（Update）; 部分更新
5. DELETE：删除（Delete）

有一些客户端只能使用GET和POST这两种方法，服务器必须接受POST模拟其他三个方法（PUT、PATCH、DELETE）。这时，客户端发出的HTTP请求，要加上X-HTTP-Method-Override属性，告诉服务器应该使用哪一个动词，覆盖POST方法。

POST /api/Person/4 HTTP/1.1 X-HTTP-Method-Override: PUT

上面代码中，X-HTTP-Method-Override 指定本次请求的方法是PUT，而不是POST。

说完了动词，我们再来说一下宾语。宾语必须是名词。宾语就是API的URL，是HTTP动词作用的对象。他应该是名词，不能是动词。比如，/articles这个URL就是正确的，而下面URL不是名词，所以都是错误的。

1. /getAllUsers
2. /createNewUser
3. /deleteAllUsers

既然URL是名词，那么应该使用复数，还是单数？这没有统一的规定，但是常见的操作是读取一个集合，比如 GET/articles（读取所有文章），这里明显应该是复数。

所以为了统一起见，建议都是用复数URL，比如GET/articles/2 要比 GET/article/2好。

我们在设计URL时要注意避免多级URL。常见的情况是，资源需要多级分类，因此很容易写出多级的URL，比如获取某个作者的某一类文章。

GET /authors/12/categories/2

这种URL不利于扩展，语义也不明确，所以更好的做法是除了第一级，其他级别都用查询字符串表达。

GET /auhtors/12?categories=2

再来一个例子，查询已发布的文章，你可能会设计成下面的URL。

GET /articles/published

使用查询字符串的写法明显更好

GET /articles?published=true

02

状态码

客户端的每一次请求，服务器都必须给出回应。回应包括HTTP状态码和数据两部分。

HTTP状态码就是一个三位数，分成5个类别。

1xx：相关信息 2xx：操作成功 3xx：重定向 4xx：客户端错误 5xx：服务器错误

总共这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的解释，客户端只需要查看状态码，就可以判断出发生了什么情况，所以服务器应该返回尽可能精确的状态码。

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状态码表示服务器已经收到请求，但还未进行处理，会在未来再处理，通常用于异步操作，下面是一个例子。

HTTP/1.1 202 Accepted { "task": { "href"：“api/company/job-management/jobs/220400”, "id"：220400 } }

3xx状态码

API用不到301状态码（永久重定向）和 302状态码（暂时重定向，307也是这个含义），因为他们可以由应用级别返回，浏览器会直接跳转，API级别可以不考虑这两种情况。

API用到 3xx 状态码，主要是 303 SeeOther，表示参考另一个URL。他与302和307的含义一样，也是“暂时重定向”，区别在于302和307用于 GET请求，而303 用于 POST、PUT和DELETE请求。收到303以后，浏览器不会自动跳转，而会让用户自己决定下一步怎么办。下面是一个例子。

HTTP/1.1 303 See Other Location：/api/orders/123

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状态码表示服务端错误。一般来说，API不会向用户透漏服务器的详细信息，所以只要两个状态就够了。

500 Internal Server Error：客户端请求有效，服务器处理时发生意外。

503 Service Unavaliable：服务器无法处理请求，一般用于网站维护状态。

03

服务器回应

不要返回纯文本

API返回的数据格式，不应该是纯文本，而应该是一个JSON对象，因为这样才能返回标准的结构化数据。所以，服务器回应的HTTP头的 Content-Type 属性要设为application/json。

客户端请求时，也要明确告诉服务器，可以接受JSON格式，即请求的HTTP头的 Accept 属性也要设为 application/json。下面是一个例子。

GET /orders/2 HTTP/1.1 Accept：application/json

发生错误时，不要返回200状态码

有一种不好的做法是，即使发生错误，也返回200状态码，把错误信息放在数据体里面，就像下面这样。

上面的代码中，解析数据体以后，才能得知操作失败。

这种做法实际上取消了状态码，这完全不可取的，正确的做法是，状态码反应发生的错误，具体的错误信息放在数据体里面返回。下面是一个例子。

API的使用未必知道，URL是怎么设计的。一个解决方法就是，在回应中，给出相关链接，便于下一步操作。这样的话用户只要记住一个URL，就可以发现其他的URL。这种方法叫做HATEOAS。

GitHub的API都在api.github.com这个域名下。访问它，就可以得到其他的URL。

上面的回应中，挑一个URL访问，又可以得到别的URL。对于用户来说，不需要记住URL设计，只要从api.github.com一步步查找就可以了。

HATEOAS的格式没有统一规定，上面的例子中，Github，将他们与其他属性放在一起。更好的做法应该是，将相关链接与其他属性分开。

HTTP/1.1 200 OK Content-Type: application/json { "status": "In progress", "links": {[ { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } , { "rel":"edit", "method": "put", "href":"/api/status/12345" } ]} }

04

总结

今日的分享到此结束，读完本文，我们就可以在日常开发中设计出更加通俗移动的RESTful API了。