api-design

一位开发者描述了在模拟餐馆世界中运行 AI 智能体的经历，发现尽管模型和框架各不相同，但同样的三个与 API 相关的错误占主导地位：猜测不存在的端点、超出预算、以及基于过时的 ID 进行操作。展示了即使修复系统后，失败模式依然持续存在。

作者解释了为什么将 Rust 的 rand crate fork 成 urandom，主要关注更小的 API 表面、更好的可发现性，以及密封的 Rng trait 来简化自定义随机数的使用。

本文解释了RESTful API的真正含义，强调了HATEOAS和超媒体作为应用状态引擎的重要性，并指出大多数现代API仅达到Richardson成熟度模型的第2级。

Alvin Sng 解释了他们的团队为何放弃使用 Stripe、WorkOS 和 Slack 的客户端 SDK，转而通过集中式包装器直接调用其 REST API。他们认为，SDK 会隐藏关键的调试细节，在生产环境中不稳定，并且容易引发反模式，而借助 AI 辅助编码，这些反模式如今可以更轻松地避免。

本文认为，为AI智能体设计API需要遵循与人类不同的原则，强调清晰性、明确性，并避免使用默认值，因为智能体可以阅读整个文档并编写大量代码。

SaaS公司TRCR构建了一个MCP服务器，为AI代理提供约150个工具，并分享了与Claude内部试用的六个关键教训：代理暴露了API缺陷，工具描述如同产品文案，自包含上下文至关重要，OAuth 2.1虽痛苦但值得，将代理与账单数据结合威力强大，内部试用改变了产品路线图。

促销推文，提供免费的 API 设计手册（限时 24 小时），涵盖基础、干净设计、模式和实践概念。

RFC 10008 定义了 HTTP QUERY 方法，这是一种安全且幂等的请求方法，允许在请求体中发送查询负载，弥合了 GET 和 POST 在查询操作之间的差距。

作者构建了一个健康食品MCP服务器，并发现智能体使用多个狭窄、受限的工具比使用一个灵活的工具表现更好，强调需要一个枯燥的工具表面来减少大语言模型的幻觉。

本文介绍了一个界面设计框架，其中每个界面都有两个通道（带内和带外）用于传达关注点。文章认为，好的设计会迫使用户面对重要的关注点，而不是让他们忽略这些关注点。

关于API版本管理实践的讨论，质疑将URL路径（例如/v1/）与语义化版本控制耦合的做法，并探讨潜在的反模式。

一篇博客文章，提议重新设计 .NET 中的 System.Diagnostics.Process 类，将仅对已启动进程有效的属性分离到一个新类中，旨在减少 API 混淆。

这篇文章来自 The Old New Thing，解释了使API变得'惰性'的概念——以一种不破坏现有应用的方式'什么都不做'——并使用在Xbox上支持打印和淘汰widget API等例子。

AEP项目为protobuf和HTTP REST API提供API设计规范和工具，托管在GitHub上。

作者讨论了同时设计 MCP 和 CLI 接口时的架构挑战，权衡了功能镜像化与利用各自独特优势（CLI 的可组合性，MCP 的安全性和可审计性）之间的利弊。

本文探讨了在API中实现幂等性的复杂性，指出处理并发请求和内容不匹配等边缘情况，比简单的重放缓存更为困难。

本文以Windows的CoInitializeSecurity为例，探讨了根据链接的SDK版本改变API行为的陷阱。讨论了DLL版本不匹配和尾调用优化等问题使这种方法复杂化。