REST API 设计规则

结论

为什么编写简洁的 REST-API 设计很重要

在当今互联互通的世界中，精心设计的 REST API 是高效且可扩展的应用程序的支柱。

编写干净的 REST API 设计至关重要，原因如下：

• 增强可用性：精心设计的 API 直观易用，适合各种技能水平的开发人员。这简化了集成并降低了学习曲线。

• 提升可维护性：简洁的代码更容易识别和修复错误、添加功能以及扩展 API，从而提升可维护性。这确保了长期稳定性并降低了开发成本。

• 提高安全性：具有适当的身份验证和授权机制的结构良好的 API 有助于防止未经授权的访问、数据泄露和其他安全漏洞。

• 增强性能：简洁的设计通过使用高效的数据结构、避免不必要的调用并最大限度地降低延迟来优化性能。这不仅能提供无缝的用户体验，还能提升应用程序的整体性能。

• 缩短开发时间：定义明确的 API 规范和清晰的文档，消除了猜测，减少了大量测试的需求，从而加快了开发速度。这节省了宝贵的开发时间和资源。

• 提升可扩展性：简洁的设计通过提供模块化架构，轻松实现可扩展性，从而轻松处理增加的流量或新功能。这确保 API 能够随着应用程序的需求而增长。

• 提高可重用性：精心设计的 API 可以在多个应用程序中重复使用，从而减少重复并提高一致性。这简化了开发过程并节省了时间和精力。

• 改进的文档：简洁的设计更易于文档化，让开发者清晰地了解 API 的工作原理以及如何有效地使用它。这减少了困惑，并提高了采用率。

URI 规则

url 的结构如下

scheme :// authority / path [?query][#fragment]

例如

https://soccer.api.org/teams/dortmund/players?name=Rona#2

有两种类型的资源

1. 集合资源：包含资源的集合。它可以类比为数据库关系

2. 单例资源：包含单个资源。可以将其比作数据库记录。

在设计 Rest-Api 时

1 集合资源应为复数

+ soccer.api.org/teams/dortmund
- soccer.api.org/team/dortmund

2 单例资源应该是单一的，可以用api背后的数据库系统中代表该资源的唯一id来代替

+soccer.api.org/teams/dortmund/players/58c1aaae-205a-11ef-aeea-a64c74618950

3 URI末尾不能有斜杠

+soccer.api.org/teams/dortmund/players
-soccer.api.org/teams/dortmund/players/

4 使用连字符代替下划线来提高 API 的可读性

+ api.blog.com/blogs/this-is-my-blog
- api.blog.com/blogs/this_is_my_blog

5 URI 路径中小写字母优先于大写字母

+ api.example.com/my-api/my-resource
- api.example.com/My-Api/My-Resource

6 URI 中没有文件扩展名

+ api.example.com/api/resource
- api.example.com/api/resource.json

7 CRUD 函数名称不应在 URI 中使用

+ DELETE api.example.com/api/resource
- GET api.example.com/api.resource/delete

8 URI 的查询部分只能用于集合资源

+ GET /users?role=admin

9 URI 的查询部分应用于对集合结果进行分页

+ GET /users?pageSize=25&pageStartIndex=50

HTTP 方法规则

PUT 可用于创建和更新资源。但是，根据最佳实践，通常建议使用 POST 创建新资源，使用 PUT 完全替换现有资源。

版本控制

对 API 进行版本控制对于以下方面很重要：

保持向后兼容性：版本控制功能允许您引入新功能，而不会破坏依赖旧 API 版本的现有集成。用户可以继续使用熟悉的端点，而寻求新功能的用户则可以采用版本控制的 API。

确保 API 的一致性和设计良好：跨版本保持一致的命名约定有助于提供用户友好的体验。更改端点会破坏这种体验，而版本控制有助于避免这种情况。

结论

现在您已经掌握了这些 REST API 设计规则，是时候将它们付诸实践了！在下面的评论中分享您的 API 创作，让我们一起构建一个设计精良、开发者友好的 API 世界。