第九篇 API设计原则与最佳实践

这篇具有很好参考价值的文章主要介绍了第九篇 API设计原则与最佳实践。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

深入浅出HTTP请求前后端交互系列专题
第一章 引言-HTTP协议基础概念和前后端分离架构请求交互概述
第二章 HTTP请求方法、状态码详解与缓存机制解析
第三章 前端发起HTTP请求
第四章 前后端数据交换格式详解
第五章 跨域资源共享(CORS):现代Web开发中的关键机制
第六篇 提升网页性能:深入解析HTTP请求优化策略(一)
第七篇 提升网页性能:深入解析HTTP请求优化策略(二)
第八篇 提升网页性能:深入解析HTTP请求优化策略(三)
第九篇 API设计原则与最佳实践
第十篇 Axios最佳实战:前端HTTP通信的王者之选
第十一篇 前沿趋势与展望:深入探索GraphQL、RESTful API、WebSocket、SSE及QUIC与HTTP/3

API设计原则与最佳实践

RESTful API设计原则

1. 资源导向

a. 资源识别

在REST架构风格中,API的设计围绕资源展开。每个URL代表一个可被唯一标识的资源,并且应当清晰、简洁和语义化。例如:

/api/users       # 用户集合资源
/api/users/42    # 特定ID为42的用户资源
b. HTTP动词的使用

通过HTTP方法来定义对资源的操作:

  • GET:用于获取资源信息。
  • POST:用于创建新资源。
  • PUT:用于替换整个资源。
  • PATCH:用于更新资源的部分内容。
  • DELETE:用于删除资源。

2. 状态转移

API应遵循无状态通信原则,每次请求都应包含所有必要的信息以完成操作,服务器不保存客户端会话状态。

3. 统一接口

确保API的一致性,不同资源类型的处理方式应当遵从相同的模式。

为了更直观地体现RESTful API的优势,我们将通过使用axios库(一个流行的JavaScript HTTP客户端)来调用RESTful API和非RESTful API的示例进行对比。

4. RESTful API 示例(axios调用)

// 引入axios库
import axios from 'axios';

// 创建RESTful API实例
const api = axios.create({
  baseURL: 'https://api.example.com/v1',
});

// 调用RESTful API资源
async function createNewOrder(orderData) {
  try {
    // POST请求创建新订单
    const response = await api.post('/orders', orderData);
    return response.data;
  } catch (error) {
    console.error('Error creating order:', error.response.data);
  }
}

async function updateOrderStatus(orderId, newStatus) {
  try {
    // PUT请求更新订单状态
    const url = `/orders/${orderId}`;
    const data = { status: newStatus };
    const response = await api.put(url, data);
    return response.data;
  } catch (error) {
    console.error('Error updating order status:', error.response.data);
  }
}

async function deleteOrder(orderId) {
  try {
    // DELETE请求删除订单
    const url = `/orders/${orderId}`;
    await api.delete(url);
  } catch (error) {
    console.error('Error deleting order:', error.response.data);
  }
}

// 使用示例
const newOrder = { /* 订单数据 */ };
createNewOrder(newOrder).then(createdOrder => console.log('Created order:', createdOrder));

const orderIdToUpdate = '123';
const updatedStatus = 'shipped';
updateOrderStatus(orderIdToUpdate, updatedStatus).then(updatedOrder => console.log('Updated order:', updatedOrder));

const orderIdToDelete = '456';
deleteOrder(orderIdToDelete).then(() => console.log('Deleted order with ID:', orderIdToDelete));

5. 非RESTful API 示例(axios调用)

// 同样引入axios库
import axios from 'axios';

// 非RESTful API的调用方式
const nonRestApi = axios.create({
  baseURL: 'https://legacy.example.com/api',
});

async function executeNonRestAction(action, data) {
  try {
    // 动作类型作为URL的一部分
    const url = `/${action}`;
    const response = await nonRestApi.post(url, data);
    return response.data;
  } catch (error) {
    console.error(`Error executing action ${action}:`, error.response.data);
  }
}

async function createLegacyOrder(orderData) {
  try {
    const response = await executeNonRestAction('CreateNewOrder', orderData);
    return response;
  } catch (error) {
    console.error('Error creating legacy order:', error.response.data);
  }
}

async function updateLegacyOrderStatus(orderId, newStatus) {
  try {
    const requestData = { orderId, status: newStatus };
    const response = await executeNonRestAction('UpdateOrderStatus', requestData);
    return response;
  } catch (error) {
    console.error('Error updating legacy order status:', error.response.data);
  }
}

// 使用示例
const legacyOrder = { /* 订单数据 */ };
createLegacyOrder(legacyOrder).then(createdOrder => console.log('Created legacy order:', createdOrder));

const legacyOrderId = '789';
const legacyUpdatedStatus = 'processing';
updateLegacyOrderStatus(legacyOrderId, legacyUpdatedStatus).then(updatedOrder => console.log('Updated legacy order:', updatedOrder));

优势对比:

  • 清晰性与一致性:RESTful API中每个HTTP方法都对应着特定的操作意图,使得API的设计更加直观且易于理解。例如,在RESTful API中,POST /orders明确表示创建新订单,而PUT /orders/:id则用于更新订单,结构一致,无需额外记忆特殊动作名。

  • 可扩展性与维护性:随着系统的发展,RESTful API可以轻松添加新的资源或资源操作,因为它们遵循统一的模式。而非RESTful API在新增功能时可能需要不断调整URL路径和动作命名规则。

  • 工具支持与缓存机制:许多开发工具和网络基础设施针对RESTful API设计提供了更好的支持,如自动补全、接口文档生成器等。此外,RESTful API更容易利用HTTP协议的缓存特性,如响应头中的Cache-Control、ETag等字段,提升性能。

  • 版本控制与兼容性:RESTful API可以通过URI路径或Accept头等方式实现版本控制,从而方便地处理升级过程中的兼容问题。非RESTful API在没有明确版本管理的情况下可能会带来更复杂的升级挑战。

通过上述对比,可以看出RESTful API在设计原则、开发者体验、长期维护以及与现有Web标准的契合度等方面具有显著优势。

HATEOAS理念与实践

1. Hypermedia as the Engine of Application State (HATEOAS)

a. 原则阐述

HATEOAS是REST的核心特性之一,它意味着API响应中应该包含足够的链接信息,使得客户端可以通过这些链接发现接下来可以执行的动作,而无需预知具体URL。

例如,在一个电商应用中,当客户端请求一个订单资源时,服务器返回的JSON响应不仅包含订单详情,还会包括链接到相关操作的URL,如:

{
  "id": "12345",
  "customer": "John Doe",
  "status": "pending",
  "total": "$100.00",
  "_links": {
    "self": { "href": "/orders/12345" },
    "cancel": { "href": "/orders/12345/cancel", "method": "POST" },
    "pay": { "href": "/orders/12345/pay", "method": "POST" },
    "items": { "href": "/orders/12345/items" }
  }
}

在这个例子中,_links属性定义了几个链接:

  • self:指向当前订单资源自身的URL。
  • cancelpay:分别指示了取消订单和支付订单的操作,通过POST方法触发这些动作,并给出了对应的动作URL。
  • items:指向与当前订单相关的商品列表资源。

这样的设计允许客户端根据接收到的数据结构动态发现并导航到不同的资源和状态,无需硬编码URL或者了解整个API的结构。这使得API更加灵活、可扩展且易于维护,同时增强了客户端的适应性,因为它们可以根据服务器提供的上下文信息来决定下一步的操作。

b. 实践举例
{
  "user": {
    "id": 42,
    "name": "Alice",
    "_links": {
      "self": { "href": "/api/users/42" },
      "edit": { "href": "/api/users/42/edit" },
      "orders": { "href": "/api/users/42/orders" }
    }
  }
}

在这个示例中,API返回的数据包含了指向当前用户资源、编辑资源以及该用户订单集合的链接,允许客户端通过解析这些链接来进行导航和交互。

在遵循HATEOAS原则的RESTful API设计中,_links或类似结构中的键(keys)并不是随意生成的,而是根据资源间关系和操作意图来命名的。例如,“self”、“next”、“prev”、“create”、"update"等都是常见的链接关系名称,它们具有一定的语义意义,客户端可以根据这些名称理解链接的目的。

对于前端来说,确实需要处理这一层额外的信息,但这样做的好处在于:

  1. 动态发现:客户端无需预先知道所有可能的接口地址或者API的变化,只需要解析返回的链接信息就能找到下一步操作的入口。

  2. 可扩展性:当API进行版本升级或添加新的功能时,只要保持链接关系的约定不变,前端应用可以继续正常工作,无需硬编码新的URL。

  3. 松耦合:前后端之间的耦合度降低,后端服务架构可以独立演化而不影响前端用户体验。

至于是否需要存储这个信息以便以后使用,这取决于具体的业务需求。有些情况下,客户端可能需要临时缓存部分链接以实现页面间的跳转或者异步操作;而在其他场景下,客户端可能会立即利用这些链接执行后续请求,并不需要持久化存储。通常,在构建响应式前端应用时,会根据当前状态和用户交互实时处理接收到的链接信息,而不是静态地存储全部链接数据。

API版本控制策略

1. 版本管理方法

i. URL路径版本化

将版本号嵌入到URL路径中,如:

/v1/users
/v2/users
ii. 请求头版本化

通过HTTP请求头传递版本信息,例如:

Accept: application/vnd.example-com.user+json;version=1.0
iii. 查询参数版本化

也可以选择将版本号作为查询参数传递:

/api/users?version=1

错误处理与反馈设计

1. 错误处理机制

a. HTTP状态码

正确使用HTTP状态码传达请求结果的状态,如4xx系列表示客户端错误,5xx系列表示服务器端错误。

b. 错误响应格式

提供统一且详细的错误消息体,通常是一个JSON对象,包括错误代码、描述信息、可能的话还包含解决问题的建议或指向帮助文档的链接。

{
  "error": "BadRequest",
  "message": "Missing required parameter 'username'",
  "status_code": 400,
  "more_info": "https://docs.example.com/errors/400"
}

通过遵循以上设计原则与最佳实践,开发者能够构建出易于理解和使用的RESTful API,并确保其在版本迭代和异常处理时具备良好的扩展性和可靠性。文章来源地址https://www.toymoban.com/news/detail-819271.html

到了这里,关于第九篇 API设计原则与最佳实践的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • 构建稳健的微服务架构:关键的微服务设计原则和最佳实践

            在现代软件开发中,微服务架构正逐渐成为构建复杂应用程序的首选方法之一。微服务架构的核心理念是将应用程序划分为一系列小型、自治的服务,每个服务专注于一个特定的业务功能。然而,要实现一个稳健的微服务架构并不仅仅是将功能拆分成微服务,还需

    2024年02月14日
    浏览(50)
  • 【最佳实践】如何设计 RESTful API ?

    良好的 API 设计是一个经常被提及的话题,特别是对于那些试图完善其 API 策略的团队来说。一个设计良好的 API 的好处包括:改进开发者体验、更快速地编写文档以及更高效地推广你的 API。但是,到底什么才构成了良好 API 设计呢?在这篇博客文章中,我将详细介绍几个为

    2024年02月07日
    浏览(32)
  • 【Git 入门教程】第九节、Git的最佳实践

    Git是一个强大的版本控制系统,可以帮助开发者管理和协调代码库。然而,正确使用Git并不总是容易。本文将介绍一些Git的最佳实践,以帮助开发者更好地利用Git来管理和协调代码库。   在使用Git时,编写有意义的提交信息是非常重要的。提交信息应该简明扼要地描述所做的

    2024年02月06日
    浏览(36)
  • 第九篇【传奇开心果系列】Ant Design Mobile of React 开发移动应用:使用内置组件实现响应式设计

    第一篇【传奇开心果系列】Ant Design Mobile of React 开发移动应用:从helloworld开始 第二篇【传奇开心果系列】Ant Design Mobile of React 开发移动应用:天气应用 第三篇【传奇开心果系列】Ant Design Mobile of React 开发移动应用:健身追踪 第四篇【传奇开心果系列】Ant Design Mobile of React 开发移

    2024年01月21日
    浏览(66)
  • 深入浅出:Zookeeper的原理与实践

    在当今的信息时代,分布式系统的应用越来越广泛,而其中一个至关重要的组成部分就是Zookeeper。作为一个分布式协调服务,Zookeeper在保障分布式系统的一致性、可靠性和可用性方面发挥着不可替代的作用。本博客旨在深入浅出地探讨Zookeeper的原理与实践,帮助读者全面理解

    2024年04月11日
    浏览(44)
  • 深入浅出 OkHttp 源码解析及应用实践

    作者:vivo 互联网服务器团队- Tie Qinrui OkHttp 在 Java 和 Android 世界中被广泛使用,深入学习源代码有助于掌握软件特性和提高编程水平。 本文首先从源代码入手简要分析了一个请求发起过程中的核心代码,接着通过流程图和架构图概括地介绍了OkHttp的整体结构,重点分析了拦

    2024年02月05日
    浏览(54)
  • 《移动互联网技术》第九章 感知与多媒体: 了解质感设计的基本原则和设计方法

    🌷🍁 博主 libin9iOak带您 Go to New World.✨🍁 🦄 个人主页——libin9iOak的博客🎐 🐳 《面试题大全》 文章图文并茂🦕生动形象🦖简单易学!欢迎大家来踩踩~🌺 🌊 《IDEA开发秘籍》学会IDEA常用操作,工作效率翻倍~💐 🪁🍁 希望本文能够给您带来一定的帮助🌸文章粗浅,敬

    2024年02月11日
    浏览(43)
  • MySQL篇---第九篇

    READ UNCOMMITTED(未提交读):事务中的修改,即使没有提交,对其他事务也都是可见 的。会导致脏读。 READ COMMITTED(提交读):事务从开始直到提交之前,所做的任何修改对其他事务都是 不可见的。会导致不可重复读。这个隔离级别,也可以叫做“不可重复读”。 REPEATABLE

    2024年02月07日
    浏览(37)
  • java基础-----第九篇

    引用计数法:每个对象有一个引用计数属性,新增一个引用时计数加1,引用释放时计数减1,计 数为0时可以回收, 可达性分析法:从 GC Roots 开始向下搜索,搜索所走过的路径称为引用链。当一个对象到 GC Roots 没有任何引用链相连时,则证明此对象是不可用的,那么虚拟机就

    2024年02月10日
    浏览(38)
  • 【第九篇:接口自动化建设】

    不要问我为什这么晚发布,这可能是我有史以来加班最晚的时候了,啊啊啊 我们之前也说过进行接口自动化建设主要是为了自动化测试服务端的逻辑,客户端与后端交互使用的主要协议的就是http协议,这也是为什么我在开篇就和大家强调过相关的基本功的学习,学习这些基

    2024年02月03日
    浏览(44)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包