RESTful设计规范

文章目录

  • 前言
  • 一、RESTful API 设计规范
  • 二、基本设计方法
    • 1、资源的命名
    • 2、资源的版本
    • 3、确定的URL
    • 4、选择HTTP方法
    • 5、选择合适的状态码
  • 三、RESTful 和 SOAP的区别
  • 总结


前言

RESTful风格是由Roy Fielding在2000年提出。它主要用于构建基于Web的应用程序,强调使用HTTP协议的基本方法(如GET,POST,PUT,DELETE)进行交互,并将每个资源表示为唯一的URI(Uniform Resource Identifiers)。它还支持使用标准数据格式,如JSON和XML,以及状态代码和标头来传达客户端和服务器之间的状态信息。使用RESTful架构风格,可以实现可扩展性、可维护性和可靠性更高的Web服务。


一、RESTful API 设计规范

下面是一些常用的 RESTful 设计规范:

  1. 使用 HTTP 方法
    使用 HTTP 方法来表示对资源的操作。常见的 HTTP 方法包括:

    • GET:获取资源
    • POST:创建资源
    • PUT:更新资源
    • DELETE:删除资源
  2. 使用 URI 表示资源
    使用 URI(Uniform Resource Identifier)来表示资源。URI 应该具有唯一性,且易于理解和使用。URI 的格式应该遵循以下规则:

    • 使用小写字母
    • 使用短横线来分隔单词
    • 不使用文件扩展名
  3. 数据传输格式
    使用 JSON 或 XML 这样的标准数据格式来传输数据。JSON 是更加常用的格式,因为它更加轻量级和易于处理。

  4. 版本控制
    在 URI 中包含版本号,以便客户端能够确定它们正在使用的 API 版本。这可以避免版本不兼容的情况发生。

  5. 错误处理
    定义标准的错误信息格式,以便客户端能够正确处理错误响应。错误信息应该包含错误代码、错误消息和可选的错误详细信息。

  6. 安全性
    使用 HTTPS 协议来保证 API 的安全性。使用身份验证和授权机制来限制对 API 的访问。

  7. 缓存
    启用客户端缓存以提高 API 的性能和响应速度。使用 ETag 和 Last-Modified 头来支持缓存机制。

  8. 频率限制
    为了防止 API 被滥用,应该启用频率限制机制。可以限制每个用户的 API 调用次数和并发连接数等。

  9. API 文档
    提供清晰、详细、易于理解的 API 文档,包括 API 的使用方法、参数和返回值等信息,以便客户端开发人员正确调用 API。

以上是一些通用的 RESTful API 设计规范,不同的应用场景和需求可能会有所不同,需要根据实际情况进行调整。


二、基本设计方法

1、资源的命名

RESTful API 应该使用名词来表示资源,而不是动词。

例:表示用户资源
正确:/users
错误:/getUsers

注意:资源表示应该是自描述的。同时资源一般为复数形式,而不是单数。

2、资源的版本

如果需要升级版本,需要在资源前增加版本信息。

例:获取v2版本的用户资源
正确:/v2/users 或 /users/v2
错误:/userV2

注意:版本应该在URI中指定,而不是在HTTP头中指定。

3、确定的URL

根据RESTful的规范,URL应该反应出资源的层次结构,因此需要为每个资源分配一个唯一的URL。

4、选择HTTP方法

对于每个URL,需要确定支持哪些HTTP方法。常见的HTTP方法如下:

方法场景例如
GET获取数据GET /api/users/1 或 GET /api/users
POST创建数据POST /api/users
PATCH差量修改数据PATCH /api/users/1
PUT全量修改数据PUT /api/users/1
DELETE删除数据DELETE /api/users/1

5、选择合适的状态码

常见的状态码如下:

状态码场景
200请求成功,通常用在同步操作时
202请求成功,通常用在异步操作时,表示请求已接受,但是还没有处理完成
400服务器无法或不会处理请求。通常用在表单参数错误
401授权错误,通常用在 Token 缺失或失效,注意 401 会触发前端跳转到登录页
403操作被拒绝,通常发生在权限不足时,注意此时务必带上详细错误信息
404没有找到对象,通常发生在使用错误的 id 查询详情
500服务器错误

其他状态码可参考 MDN Web Docs

以下是一个合乎规范的接口设计:

URL描述
/v1/api/companies公司集合
/v1/api/companies/{cid}/departments指定某个部门的集合

代码实现,可以参考如下的例子:

@RestController
@RequestMapping("/companies")
public class StudentController {// 获取全部部门信息@GetMapping("")public List<Company> getAllCompanies() {//do somethingreturn companyList;}//获取某个部门的信息@GetMapping("/{cid}")public Company getCompanyById(@PathVariable int cid) {//do somethingreturn company;  }
}

三、RESTful 和 SOAP的区别

RESTful 和 SOAP 都是Web服务架构风格,但它们之间有一些显著的区别:

  1. URL和数据传输格式:RESTful使用URL来定位特定的资源,而SOAP使用XML消息格式进行数据传输。

  2. 性能:RESTful在服务器端处理请求时,负载比较小,性能更好。而SOAP使用XML消息格式,传输数据量过大,性能相对较差。

  3. 安全性:SOAP有内置安全机制,支持多种安全协议,例如WS-Security。而RESTful并没有内置安全机制,需要使用其他的安全机制(如OAuth)来提高安全性。

  4. 编程风格:RESTful具有更加简单和自然的编程风格,而SOAP具有更加复杂和强制性的编程风格。

  5. 兼容性:RESTful比SOAP更加容易进行跨平台和跨语言的开发和集成。

因此RESTful更加轻量级和灵活,适用于简单的Web服务,也更适用于微服务架构,而SOAP更加适用于复杂的Web服务。


总结

总之,RESTful的设计规范具有易于理解、可读性高、可维护性好、可扩展性强、可移植性好、性能高和可伸缩性好等优点,因此在构建Web应用和API时被广泛采用。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/202760.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

慎用!3个容易被打的Python恶搞脚本

Python 无限恶搞朋友电脑&#xff0c;别提有多爽了&#xff0c;哈哈&#xff0c;打造自己的壁纸修改器&#xff0c;电脑无限锁屏&#xff0c; 无线弹窗&#xff0c;都在这里&#xff01;&#xff01;&#xff01; 1、修改电脑桌面壁纸 工具使用 开发环境&#xff1a;python3…

设计原则 | 依赖转置原则

一、依赖转置原则&#xff08;DIP&#xff1a;Dependence Inversion Principle&#xff09; 1、原理 高层模块不应该依赖低层模块&#xff0c;二者都应该依赖于抽象抽象不应该依赖于细节&#xff0c;细节应该依赖于抽象 2、层次化 Booch曾经说过&#xff1a;所有结构良好的面…

【408】计算机学科专业基础 - 计算机组成原理

一、计算机系统概述 【复习提示】 本章是组成原理的概述&#xff0c;考查时易针对有关概念或性能指标出选择题&#xff0c;也可能综合后续章节的内容出有关性能分析的综合题。掌握本章的基本概念&#xff0c;是学好后续章节的基础。部分知识点在初学时理解不深刻也无须担忧&am…

网店一键搬家要用到的API接口

什么是“一键搬家”&#xff1f; 我们需要了解一下什么是“一键搬家”。简单来说&#xff0c;一键搬家就是将一个网店的所有数据&#xff08;包括商品、订单、客户等&#xff09;迁移到另一个网店的过程&#xff0c;这样就可以实现网店的“搬家”。 item_get-获得淘宝商品详情…

计算机操作系统3

1.虚拟机 VM 两类虚拟机的对比&#xff1a; 2.进程 进程的特征&#xff1a; 进程状态的转换&#xff08;五大状态&#xff09; 3.进程控制原语的作用 4.线程 ​​​​​线程的属性 实现方式 5.调度算法的评价指标

没有实权的PM如何做好项目管理?

在一些公司中&#xff0c;项目经理&#xff08;PM&#xff09;可能并没有实权&#xff0c;这种情况下如何做好项目管理呢&#xff1f;实际上&#xff0c;即使没有实权&#xff0c;PM仍然可以通过一些方法来确保项目的顺利进行。 首先&#xff0c;PM可以通过建立良好的沟通渠道来…

2024年软件测试面试八股文

前言 &#xff08;第一个就刷掉一大批人&#xff09; 有很多“会自动化”的同学来咨询技术问题&#xff0c;他总会问到我一些元素定位的问题。元素定位其实都不算自动化面试的问题。 一般我都会问&#xff1a;你是定位不到吗&#xff1f;通常结果都是说确实定位不到。 做自…

pymysql.err.InternalError: (1054, “Unknown column ‘nan‘ in ‘field list‘“

记录在本地环境通过&#xff0c;然后在云环境&#xff0c;解决问题的过程&#xff1b; 最近两天遇到一个bug&#xff0c;具体就是在本地Pyhon环境运行成功&#xff0c;但是当放在云服务跑的时候&#xff0c;去屡屡报错&#xff0c;具体报错信息如下&#xff1a; pymysql.err.I…

Windows磁盘管理中硬盘无法初始化怎么办?

硬盘未出现在“此电脑”选项下的情况并不少见&#xff0c;当您打开磁盘管理&#xff0c;它要么显示为磁盘未知&#xff0c;要么显示为未分配的空间&#xff0c;或者只是不显示磁盘容量。为了访问您的硬盘并充分利用它&#xff0c;您需要对其进行初始化。不幸的是&#xff0c;您…

Apache Kafka CVE-2023-25194(metasploit版)

Step1&#xff1a;用docker搭建环境 Step2&#xff1a;docker查看映射端口 Step3&#xff1a;访问特定端口&#xff0c;然后靶标应用。 Step4&#xff1a;用metasploit进行攻击&#xff1a; 首先&#xff0c;打开metasploit&#xff0c;然后查询需要攻击的板块&#xff0…

java中AQS使用双向链表的原因是什么?

AQS&#xff08;AbstractQueuedSynchronizer&#xff09;使用双向链表的主要原因是为了实现等待队列&#xff08;Wait Queue&#xff09;。这个等待队列是用于管理在同步器上等待的线程&#xff0c;例如在获取锁时发现锁被占用&#xff0c;线程就会加入到等待队列中等待。 使用…

C++ 共享内存ShellCode跨进程传输

在计算机安全领域&#xff0c;ShellCode是一段用于利用系统漏洞或执行特定任务的机器码。为了增加攻击的难度&#xff0c;研究人员经常探索新的传递ShellCode的方式。本文介绍了一种使用共享内存的方法&#xff0c;通过该方法&#xff0c;两个本地进程可以相互传递ShellCode&am…

前端编码中快速填充内容--乱数假文

写前端页面的时候&#xff0c;如果要快速插入图片&#xff0c;可以使用 https://picsum.photos/ 详见笔者这篇博文&#xff1a; 工具网站&#xff1a;随机生成图片的网站-CSDN博客 可是&#xff0c;如果要快速填充文字内容该怎么做呢&#xff1f; 以前&#xff0c;我们都是…

【EI征稿中|SPIE出版】 第四届传感器与信息技术国际学术会议(ICSI 2024)

第四届传感器与信息技术国际学术会议&#xff08;ICSI 2024&#xff09; 2024 4th International Conference on Sensors and Information Technology&#xff08;ICSI 2024&#xff09; 第四届传感器与信息技术国际学术会议&#xff08;ICSI 2024&#xff09;将于2024年1月5…

Windows server 部署iSCSI共享磁盘搭建故障转移群集

在域环境下&#xff0c;在域控制器中配置iSCSI服务&#xff0c;配置共享网络磁盘&#xff0c;在节点服务器使用共享磁盘&#xff0c;并在节点服务器中搭建故障转移群集&#xff0c;实现故障转移 环境准备 准备3台服务器&#xff0c;配置都是8g2核&#xff0c;50g硬盘&#xf…

微服务开发:断路器详解

微服务是目前业界使用的最重要的实现方面。通过使用微服务架构&#xff0c;开发人员可以消除他们以前在单体应用程序中遇到的许多问题。展望未来&#xff0c;人们开始在微服务中搜索和采用各种模式。大多数时候&#xff0c;新模式的产生是为了解决另一个模式中出现的常见问题。…

Python IPO分析的实现

在软件开发过程中&#xff0c;IPO&#xff08;Input-Process-Output&#xff09;分析是一种常用的方法&#xff0c;用于分析软件系统的输入、处理和输出。Python作为一种功能强大的编程语言&#xff0c;提供了许多工具和库来实现IPO分析。本文将介绍如何使用Python进行IPO分析的…

指针(二)

这里写目录标题 字符指针字符指针与常量字符串的区别&#xff1a; 指针数组数组指针两者的区别&#xff1a;&数组名 &#xff0c;sizeof(arr)数组指针的使用数组参数&#xff0c;指针参数一维数组传参整型数组&#xff1a;整型指针数组&#xff1a; 一级指针传参二级指针传…

基于单片机自动饮料混合机控制系统设计

**单片机设计介绍&#xff0c;基于单片机自动饮料混合机控制系统设计 文章目录 一 概要二、功能设计设计思路 三、 软件设计原理图 五、 程序六、 文章目录 一 概要 基于单片机自动饮料混合机控制系统设计是一个涉及多个领域的复杂项目&#xff0c;包括单片机技术、传感器技术…

SQL手工注入漏洞测试(Access数据库)-墨者

———靶场专栏——— 声明&#xff1a;文章由作者weoptions学习或练习过程中的步骤及思路&#xff0c;非正式答案&#xff0c;仅供学习和参考。 靶场背景&#xff1a; 来源&#xff1a; 墨者学院 简介&#xff1a; 安全工程师"墨者"最近在练习SQL手工注入漏洞&#…