【Hacker News搬运】无抽象：我们的API设计原则

[hackernews]

Title: No Abstractions: our API design principle

无抽象：我们的API设计原则

Text:

hn link

Url: https://increase.com/articles/no-abstractions

API资源的命名和建模是设计API时最困难和最重要的部分。Increase团队在设计API时采用了一个名为“无抽象”的原则。这意味着他们不隐藏网络的底层复杂性，而是将其暴露给用户。这种方法与Stripe的设计理念相似，Stripe通过将支付网络的复杂性抽象化为用户容易理解和操作的资源，例如将支付建模为支付意图（PaymentIntent）。然而，Increase的用户不同于Stripe的用户，他们通常对支付网络有深入的了解，希望直接与网络进行交互。

Increase的API设计原则包括：

1. 现实世界命名：API资源及其属性的命名通常采用底层的网络术语。
2. 不变性：API资源模型基于实际事件，如动作或消息的发送，从而使更多资源保持不可变。
3. 按用例分离资源：如果用户对特定API资源的不同实例可以采取的操作差异很大，通常会将它们分离成多个资源。

这种设计方法可能会使API在初次查看时显得更加冗长和令人畏惧，但在长期内可以提高可预测性。Increase的工程团队已经承诺遵守这一方法，这在设计复杂API时减少了决策的认知负担。

总之，“无抽象”原则并不适合所有API，但对于正在集成其API的开发人员来说，考虑适当的抽象级别是一个有价值的练习。这取决于开发人员对产品领域的经验以及他们致力于集成的精力等因素。如果构建一个高度抽象的API，请准备好在新功能添加之前进行深入思考。如果构建一个低抽象的API，请坚持并抵制添加抽象的诱惑。

Post by: jackflintermann

Comments:

Karellen: > If you’re building an abstraction-heavy API, be prepared to think hard before adding new features. If you’re building an abstraction-light API, commit to it and resist the temptation to add abstractions when it comes along.<p>You could always do both.<p>Provide a low-level abstraction-light API that allows fine control but requires deep expertise, and write a higher-level abstraction-rich API on top of it that maps to fewer simple operations for the most common use cases - which some of your clients might be implementing their own half-baked versions of anyway.<p>If you maintain a clean separation between the two, having both in place might mean there is less pressure to add abstractions to the low-level API, or to add warts and special-cases to the high-level API. If a client wants one of those things, it already exists - in the other API.<p>Bonus points for providing materials to help your clients learn how to move from one to the other. You can attract clients who do not yet have deep knowledge of payment network internals, but are looking to improve in that direction.

Karellen: &gt；如果你正在构建一个抽象的强大的API，那么在添加新功能之前要做好认真思考的准备。如果你正在构建一个抽象的API，那么就致力于它，并在它出现时抵制添加抽象的诱惑<p> 你总是可以两者都做<p> 提供一个低级别的抽象型API，它允许精细的控制，但需要深入的专业知识，并在其之上编写一个更高级别的抽象-丰富的API，映射到最常见用例的更少简单操作-无论如何，您的一些客户可能正在实现他们自己的半生不熟版本<p> 如果在两者之间保持一个干净的分离，那么将两者都放在适当的位置可能意味着向低级API添加抽象或向高级API添加缺点和特例的压力较小。如果客户端想要其中一种东西，那么它已经存在于另一个API中<p> 提供材料以帮助您的客户学习如何从一个材料转移到另一个材料的奖励积分。你可以吸引那些对支付网络内部还没有深入了解，但希望在这个方向上有所改进的客户。

summerlight: I like the part that explains why Increase choose a different approach. Contexts matter a lot when you design something fundamental, but people usually don't appreciate this enough.

summerlight: 我喜欢解释为什么Increase选择不同方法的部分。当你设计一些基本的东西时，上下文很重要，但人们通常不会；I don’我还不够感激。

spandrew: Love the article.<p>If you love Stripe (and as a designer and tech entrepreneur I do – Stripe's simplicity and front-end skill is incredible) you might look at them and copy their ability to simplify and deliver polished experiences.<p>But the real mastery of Stripe is that they know their customers — and the simplicity they crave.<p>By this article is sounds like Increase does as well and has forged a similar laser-focus on what their customers need to build terrific design guidelines for making products. Inspiring to see.

spandrew: 喜欢这篇文章<p> 如果你喜欢Stripe（作为一名设计师和科技企业家，我也喜欢——Stripe的简单性和前端技能令人难以置信），你可以看看他们，并复制他们简化和提供卓越体验的能力<p> 但Stripe真正的优势在于他们了解自己的客户——以及他们渴望的简单<p> 通过这篇文章，听起来Increase也做了同样的事情，并将类似的激光焦点放在了客户需要什么上，以建立出色的产品设计指南。令人振奋。

cpeterso: This is similar to Domain-Driven Domain's "Ubiquitous Language" design pattern, making your implementation use the same real-world terminology used domain experts.<p><a href="https://thedomaindrivendesign.io/developing-the-ubiquitous-language/" rel="nofollow">https://thedomaindrivendesign.io/developing-the-ubiquitous-l...</a>

cpeterso: 这类似于域驱动的域；s〃；无处不在的语言&quot；设计模式，使您的实现使用与领域专家使用的真实世界术语相同的术语<p> <a href=“https:&#x2F；&x2F；thedomaindrivendesign.io&#x2F：开发无处不在的语言&#x2F”rel=“nofollow”>https:&#x20F&#x2F；域驱动程序设计.io；发展-美国</a>

l5870uoo9y: > Monthly fees for users building on Increase vary by use case.<p>I am currently adding public API access to AI-powered text-to-SQL endpoint with RAG support and the my biggest issue is the pricing. Anybody have a ballpark figure what we could be talking about here? Pricing must account for OpenAI tokens (or perhaps letting them add their own OpenAI token), database usage and likely caching/rate limiting setup down the line.

l5870uoo9y: &gt；基于Increase构建的用户的月费因用例而异<p> 我目前正在添加对支持RAG的AI-powered text-to-SQL端点的公共API访问，我最大的问题是定价。有人有大概的数字吗？我们在这里可以谈论什么？定价必须考虑到OpenAI令牌（或者可能允许他们添加自己的OpenAI令牌）、数据库使用和可能的缓存；下行速率限制设置。