RESTFul API 设计规范

RESTful API设计规范

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

 

URL设计

  • 动词+宾语(名词)

  • 动词覆盖

  • 复数URL

  • 避免多级URL

状态码

  • 必须精确

  • 2XX

  • 3XX

  • 4XX

  • 5XX

服务器响应禁忌

  • 杜绝纯文本返回

  • 发生错误时返回200

一、URL设计

动词+宾语

RESTful的核心思想就是,客户端发出的数据+操作指令都是“动词+宾语”的结构,比如GET /articles这个命令,GET是动词,/articles是宾语,动词通常就有5种HTTP请求方法,对应CRUD操作,根据 HTTP 规范,动词一律大写。

GET: 读取(Read)

POST: 新建(Create)

PUT: 更新(update)

PATCH: 部分更新

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 不是名词,所以都是错误的。

/getAllCars

/createNewCar

/deleteAllRedCars

复数URL

既然 URL 是名词,那么应该使用复数,还是单数?这没有统一的规定,但是常见的操作是读取一个集合,比如GET /articles(读取所有文章),这里明显应该是复数。为了统一起见,建议都使用复数 URL,比如GET /articles/2要好于GET /article/2。

避免多级 URL

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

GET /authors/12/categories/2

这种 URL 不利于扩展,语义也不明确,往往要想一会,才能明白含义。更好的做法是:

除了第一级,其他级别都用查询字符串表达。

GET /authors/12?categories=2

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

GET /articles/published

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

GET /articles?published=true

 

二、状态码

 

状态码必须精确

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

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

HTTP/1.1 202 Accepted
​
{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}/1.1 202 Accepted
​
{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}

 

3xx 状态码

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

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

HTTP/1.1 303 See Other Location: /api/orders/12345

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 Unavailable: 服务器无法处理请求,一般用于网站维护状态。

 

三、服务器回应

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

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

 

发送错误禁止返回200

 

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}

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

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

 

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }
}

 

课程简介 这是一门使用Java语言,SpringBoot框架,从0开发一个RESTful API应用,接近企业级的项目(我的云音乐),课程包含了基础内容,高级内容,项目封装,项目重构等知识,99%代码为手写;因为这是项目课程;所以不会深入到源码讲解某个知识点,以及原理,但会粗略的讲解下基础原理;主要是讲解如何使用系统功能,流行的第三方框架,第三方服务,完成接近企业级项目,目的是让大家,学到真正的企业级项目开发技术。 适用人群 刚刚毕业的学生 想提高职场竞争力 想学从零开发SpringBoot项目 想提升SpringBoot项目开发技术 想学习SpringBoot项目架构技术 想学习企业级项目开发技术 就是想学习SpringBoot开发 能学到什么 从0开发一个类似企业级项目 学会能做出市面上90%通用API 快速增加1到2年实际开发经验 刚毕业学完后能找到满意的工作 已经工作学完后最高涨薪30% 课程信息 全课程目前是82章,155小时,每节视频都经过精心剪辑。 在线学习分辨率最高1080P 课程知识点 1~11章:学习方法,项目架构,编码规范,Postman使用方法,Git和Github版本控制 12~16章:搭建开发环境,快速入门SpringBoot框架 17~20章:快速入门MySQL数据库 21~30章:MyBatis,登录注册,找回密码,发送短信,发送邮件,企业级接口配置 31~41章:实现歌单,歌单标签,音乐,列表分页,视频,评论,好友功能 42~48章:阿里云OSS,话题,MyBatis-plus,应用监控 49~53章:Redis使用,集成Redis,SpringCache,HTTP缓存 54~58章:Elasticsearch使用,集成Elasticsearch,使用ES搜索 59~61章:商城,集成支付宝SDK,支付宝支付 62~64章:常用哈希和加密算法,接口加密和签名 65~67章:实时挤掉用户,企业级项目测试环境,企业级接口文档 68~69章:SpringBoot全站HTTPS,自签证书,申请免费证书 70~73章:云MySQL数据库,云Redis数据库使用,轻量级应用部署环境,域名解析 74~80章:Docker使用,生产级Kubernetes集群,域名解析,集群全站HTTPS 81~82章:增强和重构项目,课程总结,后续学习计划
©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页