Restful API的设计

最新推荐文章于 2025-07-14 19:48:23 发布
转载 最新推荐文章于 2025-07-14 19:48:23 发布 · 811 阅读 · 1
文章标签：

#api #Restful

本文介绍了RESTful API设计的基本原则，包括如何定义API路径、使用HTTP动词、过滤信息、处理状态码及错误、返回结果等内容。

1）先来看github的：https://developer.github.com/v3/

转换成我们的，就是如：https://api.example.com/v1/

2）路径又称"终点"（endpoint），表示API的具体网址。

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
3）常用的HTTP动词有下面五个（括号里是对应的SQL命令）
  • GET（SELECT）：从服务器取出资源（一项或多项）。 
  • POST（CREATE）：在服务器新建一个资源。 
  • PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。 
  • PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。 
  • DELETE（DELETE）：从服务器删除资源。
还有两个不常用的HTTP动词。
  • HEAD：获取资源的元数据。 
  • OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。
例子：
  • GET /zoos：列出所有动物园 
  • POST /zoos：新建一个动物园 
  • GET /zoos/ID：获取某个指定动物园的信息 
  • PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息） 
  • PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息） 
  • DELETE /zoos/ID：删除某个动物园 
  • GET /zoos/ID/animals：列出某个指定动物园的所有动物 
  • DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物
4）过滤信息（Filtering）如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
  • ?limit=10：指定返回记录的数量 
  • ?offset=10：指定返回记录的开始位置。 
  • ?page=2&per_page=100：指定第几页，以及每页的记录数。 
  • ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。 
  • ?animal_type_id=1：指定筛选条件
参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
5）状态码（Status Codes）服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。
  • 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。 
  • 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。 
  • 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务） 
  • 204 NO CONTENT - [DELETE]：用户删除数据成功。 
  • 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。 
  • 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。 
  • 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。 
  • 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。 
  • 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。 
  • 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。 
  • 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。 
  • 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
状态码的完全列表参见 这里 。
6）错误处理（Error handling）如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。
        {
            error: "Invalid API key"
        }
7）返回结果  针对不同操作，服务器向用户返回的结果应该符合以下规范。
  • GET /collection：返回资源对象的列表（数组） 
  • GET /collection/resource：返回单个资源对象 
  • POST /collection：返回新生成的资源对象 
  • PUT /collection/resource：返回完整的资源对象 
  • PATCH /collection/resource：返回完整的资源对象 
  • DELETE /collection/resource：返回一个空文档
8）Hypermedia API RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。
比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。
{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}
上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。
{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}
从上面可以看到，如果想获取当前用户的信息，应该去访问api.github.com/user，然后就得到了下面结果。
{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}
上面代码表示，服务器给出了提示信息，以及文档的网址。
9）其他
（1）API的身份认证应该使用OAuth 2.0框架。
（2）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。


Restful API 设计
窗边
06-07 955
REST（Representational State Transfer） 是 Roy Fielding 博士在2000年他的博士论文「Architectural Styles and the Design of Network-based Software Architectures(PDF)」中提出来的一种软件架构风格。REST 服务与早前 Web Service 的 SOAP 和 XML-RPC 协议对比来讲更加简洁，现在越来越多的 Web 服务开始采用 REST 风格设计和实现。 Restful
restful api设计
03-10
RESTful API 设计 RESTful API 设计是一种架构风格，而不是严格的标准，它有很大的灵活性。它描述了一个架构样式的网络系统，RESTful 架构将服务器成前端服务器和后端服务器两部分，前端服务器为用户提供无模型的...
RESTful API 设计规范
BUG糕手的博客
07-14 875
本文介绍了RESTful API的核心概念与设计原则，涵盖HTTP方法、URL规范、状态码等关键要素。通过Spring Boot示例展示了资源创建、查询、更新和删除的实现，并提供了安全性建议和测试工具推荐。RESTful API作为现代Web开发的标准接口方式，具有结构清晰、易于维护的优势，适用于前后端分离和微服务架构场景。
RESTful API设计指南：构建高效、可扩展和易用的API
weixin_73588491的博客
07-20 4456
RESTful API（Representational State Transfer API），中文翻译过来可以表述为表述性状态转移，是一种基于HTTP协议的网络应用程序接口风格。它遵循REST架构风格的约束条件和原则，以资源为中心，使用标准的HTTP方法（如GET、POST、PUT、DELETE等）来执行操作。RESTful API强调简单性、可扩展性和可读性，使得不同系统之间的通信变得更加直观和高效。设计高质量的 RESTful API 是一个持续的过程。
RESTful API 设计原则
qq_41893505的博客
04-21 379
RESTful API 设计是一种基于 Web 的架构风格，设计良好的 REST API 应该清晰、简洁、语义明确、易扩展。以下是常见的，适合用于后端开发标准、接口规范制定，也非常适合你在面试或项目中使用 👍。
Restful API 设计规范
JngKang的博客
10-31 595
Restful API 设计规范
RESTful API设计
Just Do It
07-02 890
一、RESTful API简介 1.1 RESTfulAPI是什么 RESTful API全称是Resource Representational State Transfer(资源表述性状态转移)。 R：Resource 资源。例如：user、role、gist、issue、service、route E：Representational 表述性。数据的表现形式，例如：JSON、XML、CSV、IMG等 S：State 状态。资源的状态，例如：创建、更新等状态 T：Transfer 转移.
RESTful API 设计规范详解
热门推荐
Flag少侠的博客
07-27 1万+
客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。HTTP 状态码就是一个三位数，分成五个类别。1xx： 相关信息2xx： 操作成功3xx： 重定向4xx： 客户端错误5xx： 服务器错误这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就可以判断出发生了什么情况，所以服务器应该返回尽可能精确的状态码。
RESTful API 设计指南
m0_59267400的博客
02-02 912
RESTful API 设计强调资源、标准 HTTP 方法、无状态交互、清晰的错误处理和一致的 URL 结构。）是一种基于 HTTP 规范的架构风格，专注于通过标准化的请求方法和 URL 结构，提供一致性强、可扩展性高的 Web 服务接口。RESTful API 设计要求服务器不存储客户端状态信息，每个请求都必须包含完成该请求所需的所有信息。进行交互，使 API 设计更加直观、清晰，并遵循无状态（Stateless）的原则。对于大量数据，RESTful API 应支持分页、筛选和排序。
RESTful API 设计原则深度解析
闫磊磊
07-01 818
本文从核心原则、URL 设计、HTTP 方法应用、状态管理及面试高频问题五个维度，结合工程实践与反例分析，系统解析 RESTful API 的设计规范与最佳实践。通过系统化掌握 RESTful API 的设计原则与实践技巧，既能应对 “如何设计开放平台 API” 等综合场景，也能精准回答 “PUT 与 PATCH 的区别” 等细节问题，展现高级程序员对 Web 服务架构的系统化理解与工程落地能力。：响应中包含资源相关操作的 URL，客户端通过链接导航（如 REST 成熟度模型 Level 3）。
Restful API 设计示例
LKIDTI数据的博客
10-16 668
说明：data 主要负责存放数据，message 主要存放应用的请求日志， status 负责存储应用状态， requestId 负责存储本次请求的唯一识别码，方便排查错误。说明：最好不要出现动词，否则破坏超文本协议（HTTP）对资源的抽象的概念，这种情况可以写成/importor/extract_data 表示导入抽取数据。说明：200表示成功，4xx表示客户端异常，5xx表示服务端异常，参见HTTP 的返回码含义。说明：很容易和资源的操作的增删改查对应起来，一个路由多次使用，减少路由的数量。
RESTful API设计规范.pdf
02-13
RESTful API设计规范.pdf RESTful API设计规范是指在软件架构和设计风格中，遵循一组设计原则和约束条件，以降低开发的复杂性，提高系统的可扩展性。RESTful架构的核心是面向资源，每个网址代表一种资源，因此网址...
RESTful API 设计最佳实践
03-20
以下是对RESTful API设计核心概念的详细解释： 1. **资源**：在RESTful API中，资源是系统中的核心实体，例如“tickets”或“messages”。资源通过唯一的URI（统一资源标识符）进行定位，使得客户端可以通过HTTP...
C/C++语言的程序运行时间精确测量工具开发
最新发布
10-07
【源码免费下载链接】：https://renmaiwang.cn/s/egzoj 在C/C++编程中，精确地测量程序运行时间是一项重要的任务，这有助于优化代码性能、调试和理解程序的效率。本文将深入探讨如何利用C/C++实现程序运行时间的精确测量，精度可达毫秒级别。我们有两种常用的方法来测量程序运行时间：一种是基于标准库函数`<ctime>`中的`clock()`，另一种是基于操作系统特定的API，如POSIX的`gettimeofday()`或Windows的`QueryPerformanceCounter()`。1. `clock()` 函数：`<ctime>`库中的`clock()`函数提供了一个简单的计时器，它返回自程序开始执行以来到调用`clock()`函数为止的CPU时钟周期数。这个值可以通过除以`CLOCKS_PER_SEC`常量（通常等于`CLOCKS_PER_SEC = 1000000`）转换为秒。然而，`clock()`函数的精度依赖于系统时钟的分辨率，可能不适用于毫秒级别的测量。```cpp#include <ctime>int main() { clock_t start = clock(); // 这里是你的程序代码 clock_t end = clock(); double duration = static_cast<double>(end - start) / CLOCKS_PER_SEC; std::cout << "程序运行时间: " << duration << " 秒" << std::endl; return 0;}```2. `gettimeofday()` 函数：在支持POSIX的系统（如Linux）中，`<sys/time.h>`头文件提供了`gettimeofday()`函数，它可以获取当前时间，包括微秒级别的精度。这种方法可
CAN 总线协议完整学习与开发指南.zip
10-07
can总线
MQTT协议完整学习与开发指南.zip
10-07
mqtt
HW3000 demo code (STM8S105 IAR)( A版本).zip
10-07
【HW3000的收发程序】是一个与硬件设备HW3000相关的软件实现，主要用于处理数据的发送和接收。在这个项目中，我们关注的是一个基于STM8S105微控制器的示例代码，它使用了IAR集成开发环境。这个压缩包包含了名为"A版本"的代码示例，这表明可能还有其他版本存在，例如"B版本"或"C版本"，每个版本可能对应不同的功能改进或优化。 STM8S105是意法半导体（STMicroelectronics）推出的一款8位微控制器，属于STM8系列。该芯片具有高性能、低功耗的特点，常用于各种嵌入式系统，如工业控制、消费电子和汽车电子等领域。IAR是一个流行的嵌入式系统开发工具，提供了一整套集成开发环境（IDE），包括编译器、调试器和其他辅助工具，使得开发者能够方便地编写、编译和调试STM8S105上的代码。 在HW3000的收发程序中，我们预计会看到以下关键知识点： 1. **硬件接口**：为了与HW3000通信，代码可能定义了特定的GPIO引脚来控制数据传输和握手信号。这些引脚可能是通过STM8S105的端口和引脚配置来实现的。 2. **通信协议**：HW3000可能使用某种串行通信协议，如SPI、I2C或UART。代码会包含相应的初始化函数和数据传输函数，以遵循该协议。 3. **中断服务例程**：为了实时响应数据收发事件，程序可能使用中断服务例程（ISR）。当硬件检测到新的数据或发送完成时，中断将被触发，并执行相应处理。 4. **数据缓冲区管理**：在发送和接收数据时，可能需要使用缓冲区来存储待发送的数据或接收的数据包。代码会包含关于如何填充、读取和清空缓冲区的逻辑。 5. **错误检测和处理**：良好的通信程序会包含错误检测机制，如CRC校验或奇偶校验，以及错误处理代码，以确保数据的完整性和正确性。 6. **同步机制**：为了确保发送和接收的顺序，可能使用了互斥锁、信号量或其他同步原语来避免数据冲突。 7. **代码注释**：描述中提到代码注释详细且通俗易懂，这意味着开发者可以很容易地理解每一部分的功能，这对于理解和维护代码至关重要。 由于这是一个"A版本"的代码，我们可以假设它可能是项目的基础版本，可能随着项目的进展，后续的版本会包含更高级的功能、优化的性能或者修复的已知问题。对这个压缩包的深入研究将有助于我们了解HW3000硬件的工作原理，以及如何有效地与之进行软件交互。
CISCO交换机如何删除VLAN
10-07
【源码免费下载链接】：https://renmaiwang.cn/s/fmfod 在 Cisco 交换机上管理 VLAN 是网络管理员日常工作中不可或缺的一部分。VLAN（虚拟局域网）的创建和删除有助于组织网络流量、提高安全性并优化网络性能。然而，在某些情况下，需要删除不再使用的 VLAN，以避免资源浪费和潜在的配置冲突。在 Cisco 交换机中，简单地执行`no vlan`命令并不能彻底删除一个 VLAN，因为这只会从 VLAN 数据库中移除 VLAN 的定义，而不会处理相关的接口配置。以下是一步一步的详细步骤，确保完全删除一个 VLAN：1. **连接到交换机**：可以通过控制台口或使用 Telnet 远程连接至交换机。一旦建立连接，将进入用户模式（User EXEC Mode），提示符显示为`<Switch>`。2. **切换到特权模式**：在用户模式下输入`en`命令，切换到特权模式（Privileged EXEC Mode），提示符变为`Switch#`。3. **进入全局配置模式**：在特权模式下，输入`conf t`命令，进入全局配置模式，此时提示符变为`Switch(config)#`。4. **移除接口上的 VLAN 配置**：如果 VLAN 已分配给接口，则必须先从接口上移除 VLAN 配置。例如，在删除 VLAN 20 时，可以输入`int f0/1`进入接口配置模式，然后执行命令`no switchport access vlan 20`。如果 VLAN 20 被多个接口使用，则需要对每个接口重复此操作。5. **移除 VLAN 接口**：接下来，删除 VLAN 接口，输入`no interface vlan 20`。这将解除 VLAN 20 对其所有相关接口的配置。6. **彻底删除 VLAN**：最后，执行命令`no vlan 20`，从 VLA
二分图完美匹配（匈牙利算法）
10-07
【源码免费下载链接】：https://renmaiwang.cn/s/5drve 二分图完美匹配属于图论中的一个重要概念，在该领域中具有特殊意义。特别是在研究匹配理论时，这一概念往往成为核心内容之一。将节点集合划分为两个互不相交的部分，其中每一部分内部的节点之间不会直接相连。完美匹配指的是在这样一个结构下，通过特定方式使得每个节点都能与另一组中的唯一一个节点建立连接，并且没有任何剩余的未配对节点存在。匈牙利算法作为一种高效的计算方法，在解决二分图最大匹配问题时发挥着关键作用。该算法的基本思路在于逐步构建增广路径来扩大已有的匹配规模，最终达到最大匹配目标。具体而言，一条增广路径是一条连接两个未被配对节点的路径，在其中交替出现已配对与未配对的状态。每次找到这样的一条路径后，通过调整相关边的方向和位置，可以实现匹配数量的增加。在提供的代码实现中，匈牙利算法主要分为以下几个部分：初始化阶段、增广路径搜索函数、主处理函数以及最终输出结果的部分。初始化阶段主要是定义必要的变量参数；增广路径搜索函数用于寻找能够提升当前匹配程度的路径；主处理函数则通过调用上述辅助函数，系统地完成整个匹配过程，并输出最终的匹配数量信息。该算法在多个实际应用场景中展现出强大的实用性，例如解决任务分配、婚姻配对以及网络路由等问题时都发挥着不可替代的作用。
RESTful API设计指南
"RESTful API设计规则书，作者Mark Massé，详细讲述了如何设计RESTful API。" 本书《RESTful API设计规则书》是Mark Massé的作品，主要关注于RESTful API的设计方法。REST（Representational State Transfer）是...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值