如何优雅的设计RESTful API?这是我看过讲的最清晰的文章!

栏目: 后端 · 前端 · 发布时间: 5年前

内容简介:还没关注?快动动手指!

还没关注?

快动动手指!

聊技术、论职场!

为IT人打造一个“有温度”的 狸猫技术窝

RESTful  是目前最流行的 API 设计规范,用于 Web 数据接口的设计。它的大原则容易把握,但是细节不容易做对。

本文总结 RESTful 的设计细节,介绍如何设计出易于理解和使用的 API。

一、URL 设计

1.1 动词 + 宾语

RESTful 的核心思想就是,客户端发出的数据操作指令都是"动词 + 宾语"的结构。

比如,GET /articles这个命令,GET是动词,/articles是宾语。 动词通常就是五种 HTTP 方法,对应 CRUD 操作。

根据 HTTP 规范,动词一律大写。

1.2 动词的覆盖

有些客户端只能使用GET和POST这两种方法,服务器必须接受POST模拟其他三个方法(PUT、PATCH、DELETE)

这时,客户端发出的 HTTP 请求,要加上X-HTTP-Method-Override属性,告诉服务器应该使用哪一个动词,覆盖POST方法。

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

1.3 宾语必须是名词

宾语就是 API 的 URL,是 HTTP 动词作用的对象。它应该是名词,不能是动词。

比如,/articles这个 URL 就是正确的,而下面的 URL 不是名词,所以都是错误的。

1.4 复数 URL

既然 URL 是名词,那么应该使用复数,还是单数?这没有统一的规定,但是常见的操作是读取一个集合。

比如GET /articles(读取所有文章),这里明显应该是复数。

为了统一起见,建议都使用复数 URL,比如GET /articles/2要好于GET /article/2。

1.5 避免多级 URL

常见的情况是,资源需要多级分类,因此很容易写出多级的 URL,比如获取某个作者的某一类文章。

这种 URL 不利于扩展,语义也不明确,往往要想一会,才能明白含义。

更好的做法是,除了第一级,其他级别都用查询字符串表达。

下面是另一个例子,查询已发布的文章。你可能会设计成下面的 URL。

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

二、状态码

2.1 状态码必须精确

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

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

这五大类总共包含100多种状态码,覆盖了绝大部分可能遇到的情况。

每一种状态码都有标准的(或者约定的)解释,客户端只需查看状态码,就可以判断出发生了什么情况,所以服务器应该返回尽可能精确的状态码。

API 不需要1xx状态码,下面介绍其他四类状态码的精确含义。

2.2 2xx 状态码

200 状态码表示操作成功,但是不同的方法可以返回更精确的状态码。

上面代码中, POST 返回 201 状态码,表示生成了新的资源; DELETE 返回 204 状态码,表示资源已经不存在。

此外, 202 Accepted 状态码表示服务器已经收到请求,但还未进行处理,会在未来再处理,通常用于异步操作。

下面是一个例子。

2.3 3xx 状态码

API 用不到301状态码(永久重定向)和302状态码(暂时重定向,307也是这个含义)

因为它们可以由应用级别返回,浏览器会直接跳转,API 级别可以不考虑这两种情况。

API 用到的3xx状态码,主要是303 See Other,表示参考另一个 URL。

它与302和307的含义一样,也是"暂时重定向",区别在于302和307用于GET请求,而303用于POST、PUT和DELETE请求。

收到303以后,浏览器不会自动跳转,而会让用户自己决定下一步怎么办。

下面是一个例子。

2.4 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:客户端的请求次数超过限额。

2.5 5xx 状态码

5xx状态码表示服务端错误。一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。

  • 500 Internal Server Error:客户端请求有效,服务器处理时发生了意外

  • 503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态

三、服务器回应

3.1 不要返回纯本文

API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。

所以,服务器回应的 HTTP 头的Content-Type属性要设为application/json。

客户端请求时,也要明确告诉服务器,可以接受 JSON 格式,即请求的 HTTP 头的ACCEPT属性也要设成application/json。

下面是一个例子。

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

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

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

这张做法实际上取消了状态码,这是完全不可取的。正确的做法是,状态码反映发生的错误,具体的错误信息放在数据体里面返回。

下面是一个例子。

3.3 提供链接

API 的使用者未必知道,URL 是怎么设计的。一个解决方法就是,在回应中,给出相关链接,便于下一步操作。

这样的话,用户只要记住一个 URL,就可以发现其他的 URL。这种方法叫做 HATEOAS。

举例来说,GitHub 的 API 都在 api.github.com 这个域名。访问它,就可以得到其他 URL。

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

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

End

作者: 阮一峰

来源:

http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html

本文版权归作者所有

为您推荐

  1. 如何设计一个百万级用户的抽奖系统?

  2. 阿里二面:设计一个电商平台积分兑换系统!

  3. 扎心一问!你凭什么成为top1%的 Java 工程师?

  4. 【干货走一波】千万级用户的大型网站,应该如何设计其高并发架构?

  5. PK光明顶?江湖上流传的几大消息队列门派,到底有什么本质区别?

  6. 扒一扒 JVM 的垃圾回收机制,拿大厂offer少不了它!

  7. 面试阿里?如果对别人开源的Rocket MQ了如指掌,岂不是很加分?

  8. 百度、腾讯热门面试题:聊聊Unix与Java的IO模型?(含详细解析)

  9. 35岁的大龄 码农 们,如何才能不被社会淘汰掉?

  10. 一步一图,带你走进Netty的世界!

  11. 想要去阿里面试?你必须得跨过JVM这道坎!

  12. 你连Nginx怎么转发给你请求都说不清楚,还好意思说自己不是CRUD工程师?

长按下图二维码,即刻关注【 狸猫技术窝

阿里、京东、美团、字节跳动

顶尖技术专家 坐镇

为IT人打造一个 “有温度” 的技术窝!

如何优雅的设计RESTful API?这是我看过讲的最清晰的文章!


以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

新榜样

新榜样

新榜 编著 / 电子工业出版社 / 2016-1 / 50.00元

本书为“新榜”全新打造的新媒体运营实战指南,全书基于对当前各类公众号的对比分析,阐述互联网时代各类公众号运营之道。全书分为五个部分,分别为:如何让政务公众号接地气,如何让自媒体公众号重获新生,如何做垂直领域的特色公众号,新媒体深度人物,以及新媒体深度分析等。一起来看看 《新榜样》 这本书的介绍吧!

JSON 在线解析
JSON 在线解析

在线 JSON 格式化工具

图片转BASE64编码
图片转BASE64编码

在线图片转Base64编码工具

XML、JSON 在线转换
XML、JSON 在线转换

在线XML、JSON转换工具