RESTful规范Api最佳设计实践

最新推荐文章于 2023-10-12 10:54:14 发布
最新推荐文章于 2023-10-12 10:54:14 发布
阅读量131 收藏
点赞数 1
分类专栏： Spring Boot
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_43674132/article/details/103188565
版权

RESTful规范Api最佳设计实践

RESTful是目前比较流行的接口路径设计规范，基于HTTP，一般使用JSON方式定义，通过不同HttpMethod来定义对应接口的资源动作，如：新增（POST）、删除（DELETE）、更新（PUT、PATCH）、查询（GET）等。

路径设计

在 RESTful设计规范内，每一个接口被认为是一个资源请求，下面我们针对每一种资源类型来看下API路径设计。

路径设计的 注意事项如下所示：

  • 资源名使用复数

  • 资源名使用名词

  • 路径内不带特殊字符

  • 避免多级URL

新增资源

请求方式示例路径
POSThttps://api.yuqiyu.com/v1/users

新增资源使用 POST方式来定义接口，新增资源数据通过 RequestBody方式进行传递，如下所示：

curl -X POST -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users -d '{

"name": "小明",

"age": 25,

"address": "山东济南"

}'

新增资源后接口应该返回该资源的唯一标识，比如：主键值。

{

"id" : 1,

"name" : "小明"

}
通过返回的唯一标识来操作该资源的其他数据接口。

删除资源

请求方式示例路径备注
DELETEhttps://api.yuqiyu.com/v1/users批量删除资源
DELETEhttps://api.yuqiyu.com/v1/users/{id}删除单个资源

删除资源使用 DELETE方式来定义接口。

  •  

    根据主键值删除单个资源

     

    将资源的 主键值通过路径的方式传递给接口。

curl -X DELETE https://api.yuqiyu.com/v1/users/1

  •  

    删除多个资源

     

    删除多个资源时通过 RequestBody方式进行传递删除条件的数据列表，上面示例中通过资源的主键值集合作为删除条件，当然也可以通过资源的其他元素作为删除的条件，比如： name

curl -X DELETE -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users -d '{

"userIds": [

]

}'

更新资源

请求方式示例路径备注
PUThttps://api.yuqiyu.com/v1/users/{id}更新单个资源的全部元素
PATCHhttps://api.yuqiyu.com/v1/users/{id}更新单个资源的部分元素

在更新资源数据时使用 PUT方式比较多，也是比较常见的，如下所示：

curl -X PUT -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users/1 -d '{

"name": "小明",

"age": 25,

"address": "山东济南"

}'

查询单个资源

请求方式示例路径备注
GEThttps://api.yuqiyu.com/v1/users/{id}查询单个资源
GEThttps://api.yuqiyu.com/v1/users?name={name}非唯一标识查询资源
   

  •  

    唯一标识查询单个资源

     

  
 

  1. curl https://api.yuqiyu.com/v1/users/1

  
   

通过唯一标识查询资源时，使用路径方式传递标识值，体现出层级关系。

  

  •  

    非唯一标识查询单个资源

     

  
 

  1. curl https://api.yuqiyu.com/v1/users?name=小明

  
   

查询资源数据时不仅仅都是通过唯一标识值作为查询条件，也可能会使用资源对象内的某一个元素作为查询条件。

  
   

分页查询资源

  
请求方式示例路径
GEThttps://api.yuqiyu.com/v1/users?page=1&size=20

分页查询资源时，我们一般需要传递两个参数作为分页的条件， page代表了当前分页的页码， size则代表了每页查询的资源数量。

curl https://api.yuqiyu.com/v1/users?page=1&size=20

如果分页时需要传递查询条件，可以继续追加请求参数。

https://api.yuqiyu.com/v1/users?page=1&size=20&name=小明

动作资源

有时我们需要有动作性的修改某一个资源的元素内容，比如：重置密码。

请求方式示例路径备注
POSThttps://api.yuqiyu.com/v1/users/{id}/actions/forget-password-

用户的唯一标识在请求路径中进行传递，而修改后的密码通过 RequestBody方式进行传递，如下所示：

curl -X POST -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users/1/actions/forget-password -d '{

"newPassword": "123456"

}'

版本号

版本号是用于区分 Api接口的新老标准，比较流行的分别是 接口路径、 头信息这两种方式传递。

  •  

    接口路径方式

    我们在部署接口时约定不同版本的请求使用 HTTP代理转发到对应版本的接口网关，常用的请求转发代理比如使用： Nginx等。

    这种方式存在一个弊端，如果多个版本同时将请求转发到同一个 网关时，会导致具体版本的请求转发失败，我们访问 v1时可能会转发到 v2，这并不是我们期望的结果，当然可以在 网关添加一层拦截器，通过提取路径上班的版本号来进行控制转发。

  •  

    头信息方式

    我们可以将访问的接口版本通过 HttpHeader的方式进行传递，在 网关根据提取到的头信息进行控制转发到对应版本的服务，这种方式资源路径的展现形式不会因为版本的不同而变化。

     

    这两个版本的请求可能请求参数、返回值都不一样，但是请求的路径是一样的。

    版本头信息的 Key可以根据自身情况进行定义，推荐使用 Accpet形式，详见Versioning REST Services。

# v1版本的请求

curl -H 'Accept-Version：v1' https://api.yuqiyu.com/users/1

# v2版本的请求

curl -H 'Access-Version: v2' https://api.yuqiyu.com/users/1

状态码

在 RESTful设计规范内我们需要充分的里面 HttpStatus请求的状态码来判断一个请求发送状态，本次请求是否有效，常见的 HttpStatus状态码如下所示：

状态码发生场景
200请求成功
201新资源创建成功
204没有任何内容返回
400传递的参数格式不正确
401没有权限访问
403资源受保护
404访问的路径不正确
405访问方式不正确，GET请求使用POST方式访问
410地址已经被转移，不可用
415要求接口返回的格式不正确，比如：客户端需要JSON格式，接口返回的是XML
429客户端请求次数超过限额
500访问的接口出现系统异常
503服务不可用，服务一般处于维护状态。

针对不同的状态码我们要做出不同的反馈，下面我们先来看一个常见的 参数异常错误响应设计方式：

# 发起请求

curl -X POST -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users -d '{

"name": "",

"age": 25,

"address": "山东济南"

}'

# 响应状态

HttpStatus 200

# 响应内容

{

"code": "400",

"message": "用户名必填."

}

在服务端我们可以控制不同状态码、不同异常的固定返回格式，不应该将所有的异常请求都返回 200，然后对应返回错误，正确的方式：​​​​​​​

# 发起请求

curl -X POST -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users -d '{

"name": "",

"age": 25,

"address": "山东济南"

}'

# 响应状态

HttpStatus 400

# 响应内容

{

"error": "Bad Request",

"message": "用户名必填."

}

响应格式

接口的响应格式应该 统一。

每一个请求成功的接口返回值外层格式应该统一，在服务端可以采用实体方式进行泛型返回。

如下所示：​​​​​​​

/**

* Api统一响应实体

* {@link #data } 每个不同的接口响应的数据内容

* {@link #code } 业务异常响应状态码

* {@link #errorMsg} 业务异常消息内容

* {@link #timestamp} 接口响应的时间戳

*

* @author 小明
*/

@Data

public class ApiResponse<T> implements Serializable {

private T data;

private String code;

private String errorMsg;

private Long timestamp;

}

  1. data

    由于每一个 API的响应数据类型不一致，所以在上面采用的泛型的泛型进行返回， data可以返回任意类型的数据。

  2.  

    code

    业务逻辑异常码，比如：USERNOTFOUND（用户不存在）这是接口的约定

  3.  

    errorMsg

    对应 code值得描述。

  4.  

    timestamp

    请求响应的时间戳

     

总结

RESTful是 API的设计规范，并不是所有的接口都应该遵循这一套规范来设计，不过我们在设计初期更应该规范性，这样我们在后期阅读代码时根据路径以及请求方式就可以了解接口的主要完成的工作。

凌枫zero
关注
  • 1
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
【架构师必看】RESTful API规范及最佳实践
禅与计算机程序设计艺术
10-01 1472
作者：禅与计算机程序设计艺术 1.简介 前言 API（Application Programming Interface）应用程序编程接口，是一个开放平台，它允许不同应用之间进行信息交流和服务互通。而RESTful API（Representational State Transfer Represen
Restful API的设计与实践
虫草
12-08 1646
Restful这个名称应该很多人都不陌生，但是我发现不少人对Restful存在或多或少的理解偏差，其中不泛比较厉害的程序员，所以有必要为Restful来“正名”。Restful是一种软件架构风格，设计风格而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。（详见百度百科介绍）Restful的关键是抽取资
RESTful API设计最佳实践（转译）
一陈的博客
02-22 227
RESTful API设计最佳实践（转译）每个资源，使用两个URL用名词替代动词表示URL使用HTTP方法来操作URL在表示集合URL上，使用POST来创建新的资源在表示特定袁术URL上，使用PUT来表示更新资源坚持使用复数名词使用“？”来拼接可选或者复杂的参数使用HTTP状态码提供有效的错误码或错误提示使用驼峰规则表示属性名称总是强制在URL中包含版本号提供分页查询支持对非资源型响应使用动词表达考虑特定资源和跨域资源查找通过API，提供其他链接 发布资源的URL改如何设计？名词使用复数或者单数？对同一个资
RESTful设计规范
Hello LinWoW~ ⊙o⊙
07-01 715
文章目录RESTful设计规范协议域名版本（Versioning）路径（Endpoint）HTTP动词过滤信息（Filtering）状态码（Status Codes）错误处理（Error handling）返回结果Hypermedia API RESTful REST与技术无关，代表的是一种软件架构风格，REST是Representational State Transfer的简称，中文翻译为“表...
Springboot 全局异常、返回实体配置
ybb_ymm的专栏
07-04 514
首先，一个项目中为了清晰、统一的处理返回信息，所以需要封装一个返回对象，这个对象需要有响应code码、响应code码对应的描述信息、以及返回数据对象。下面我们来看一下具体代码： public class ApiResult implements Serializable { /** * 响应码 */ private String resultCode; /** * 响应描述 */ public String msg; /** * 返回数据对象 */ public Ma
RESTful API设计规范
10-16
以下是对RESTful API设计的一些关键规范和最佳实践的详细解读： #### 一、统一接口原则 - **概念**：RESTful架构的核心理念之一便是遵循统一接口的原则。这意味着，无论何种资源，都应通过一组有限预定义的操作来...
RESTful API 设计最佳实践与规范
![RESTful API 设计最佳实践与规范]...# 1. RESTful API 的基本概念 RESTful API（Represent
RESTful API设计最佳实践
![RESTful API设计最佳实践]...# 1. RESTful API基础概念 RESTful API，即符合REST架构风格的API
Restful API设计规范与最佳实践分享
Restful API（Representational State Transfer）是一种基于REST架构风格设计的API，它使用统一的接口（如HTTP协议）来提供服务，具有易读性、灵活性、可伸缩性等特点。Restful API通常通过URI来标识资源，通过HTTP...
Java 如何设计 API 接口，实现统一格式返回？
fang.lovest.yang的博客
08-20 1352
前言 在移动互联网，分布式、微服务盛行的今天，现在项目绝大部分都采用的微服务框架，前后端分离方式，（题外话：前后端的工作职责越来越明确，现在的前端都称之为大前端，技术栈以及生态圈都已经非常成熟；以前后端人员瞧不起前端人员，那现在后端人员要重新认识一下前端，前端已经很成体系了） 一般系统的大致整体架构图如下： 需要说明的是，有些小伙伴会回复说，这个架构太简单了吧，太low了，什么网关啊，缓存啊，消息中间件啊，都没有。 因为老顾这篇主要介绍的是API接口，所以我..
前后端接口规范 - RESTful 版
最新发布
如果相遇，那么你好哦~
10-12 470
关于如何设计良好风格的 RESTful API.
response返回封装类
qq_27185561的博客
10-23 7089
response返回封装类 ServerResponse public class ServerResponse&lt;T&gt; implements Serializable { private int status; private String msg; private T data; private ServerResponse(int status) { this....
public class Classes implements Serializable{
云计算?
02-28 1429
package com.tfy.heibernate.mangtoone; import java.io.Serializable; import java.util.Set; public class Classes implements Serializable{private Long cid;private String cname;private String descriptio...
API自定义响应类以及对应状态码
会飞的海象
08-27 1456
package com.test.beans; import com.test.enums.StatusEnum; import java.io.Serializable; /** @author hy.ding */ public class ResponseBean implements Serializable { private static final long serialVers...
RestFul风格传参
weixin_44976835的博客
01-04 6306
RestFul风格就是所有参数都由/传递，而不是传统的?xx&xx形式 例如：写一个Controller： package controller; import org.springframework.stereotype.Controller; import org.springframework.ui.Model; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.we
分页需要传递几个参数
热门推荐
enthan809882的博客
10-24 1万+
最多2个: 1、pageNo，因为点第几页是用户决定的。所以需要传参数。 2、pageSize，因为用户可选每页展示条数(如10，20，50等)(其实如果固定分页大小的话,这个参数可以不传) 其他的参数都是可以计算出来的。 ...
MDN文档-HTTP概述
u011135410的专栏
10-19 1087
本文是记录查看MDN文档之后关于HTTP的一些个人离散的记忆点，更详细内容可以查看链接：https://developer.mozilla.org/zh-CN/docs/Web/HTTP HTTP概述 HTTP可以说是互联网的重要基石之一，我们平时最普通的浏览器行为其实就是在发送HTTP请求（当然更多是HTTPS请求，相比HTTP多了SSL的安全证书认证，来判定该网站是真实合法的‘好’网站）。...
MDN学习笔记---原型链
weixin_43995279的博客
04-28 699
学习目标： 1、理解JS对象原型 2、原型链如何工作 3、如何向prototype属性添加新方法 1、理解对象原型 每个对象都有一个原型对象（prototype），可以通过Object.getPrototypeOf()或者已弃用的__proto__属性获得，__proto__属性是通过构造函数的prototype属性派生的. 对象的原型与构造函数prototype属性的区别：前者在每个实例对象里都...
RESTful API 设计实战与最佳实践
"RESTful API设计最佳实践探讨了如何在实际应用中创建易于使用、部署灵活且优雅的API，强调了RESTful URL和行动的重要性，并提出了API设计应遵循的原则，包括遵循标准、对程序员友好、简单直观、具备灵活性以及关注...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值