问题标签 [api-design]

我目前正在开发一个 API，我决定的一件事是拥有一个 gateway.cfm 页面，客户端将请求发送到该页面并带有 sig 进行验证等，网关处理请求并通过调用组件将结果发回需要。

例如 gateway.cfm?component=getBooks&sig=232345343 将调用 getbooks 组件并返回 JSON。

忽略任何安全问题，由于所有请求都将转到一页，因此该 API 是否会受到影响和性能？或者，无论所有请求是否都转到同一个页面，这对 Web 服务器都无关紧要。

这也将由 SSL 保护。

我查看了 API 版本控制的最佳实践？，但我不太相信答案，所以我用一个更具体的例子再次质疑版本控制部分。我有两个 URI（一个带有版本控制作为 URI 的一部分，一个没有）：

我怀疑第一个链接是否表达了 REST 的想法。我感到http://xxxx/v1/user/123困惑，因为它暗示有一天会有更高的 api 版本，比如http://xxxx/v2/user/123. 但这在 REST 术语中没有意义，api 版本本身是 HTTP 1.0 或 1.1，它已经在 HTTP 请求内部发送。这种以 REST 资源为中心的视图与 SOAP 或 Java 接口等其他 api 接口非常不同（在这些接口中，api 版本的限定名称很常见）。

在 REST 中，版本控制唯一有意义的是该资源的表示（例如，添加或删除新字段）。此版本控制属于内容协商的一部分，例如：

也有人可能会争辩说，这种版本的内容协商可能是路径内 URI 的一部分，但我发现它违反直觉，因为您最终可能会为同一资源使用不同的 URI，并且必须在某些时候维护重定向。

总结一下：在 REST URI 中没有 api 版本控制，只有资源表示的版本控制。表示版本信息属于内容协商（如 queryParam 或 HTTP 'Accept'）。

你怎么看？你会不同意/同意哪些事情？

C API 函数分配其输出或让用户指定输出缓冲区是个好主意吗？例如：

对比

更具体地说，我想知道为什么 Win32 API 主要使用第二种情况（例如GetWindowText、LookupAccountSid）。如果一个 API 函数知道输出有多大，为什么用户要尝试猜测输出大小？我找不到任何关于为什么要使用第二种情况的信息。

另外： LookupAccountSid 示例特别糟糕。它在内部使用 LSA API，为调用者分配输出。然后 LookupAccountSid 让用户分配一个缓冲区（并猜测正确的缓冲区大小），它可以只返回 LSA 的输出！为什么？

我正在阅读一些关于如何很好地设计库或 API 的内容，并偶然发现了 Joshua Bloch 在 Google Tech Talks 上的精彩演讲。现在，虽然我离专业的 API 开发人员还差得很远，但我认为编写一堆类/函数是相似的，尽管同一件事的缩小版 - 动作的明确分离，易用性和令人愉悦的使用，鼓励干净的代码， ETC。

我正在浏览一些广泛使用的开源 Java 代码并得到了这个想法（没有什么新东西，只是把它清楚地提出来......）

让我们举一个伪代码示例（或者可能是 BASIC 的一些方言）：

现在受到 Java 代码的启发，我希望能够做这样的事情：

我的问题是：
还有其他人从这样的伪代码开始设计 API 吗？

小东西是个好主意吗？说最多 10 个类，每个类可能有 10 个方法，每个方法里面的代码不超过 5-6 行。这显然只是一组粗略的数字来显示要设计的类的大小 - 远不及完整的 API，而不仅仅是一个爱好项目 -一个专业的包，做一些小事但做得很好。

有没有人发现这种方法有任何严重的缺点？

我认为一个真正的好处是它迫使你首先写下你的用例。

另一件事是名词和动词保持简单，使您的最终产品能够避开MultiPhraseAbstractParadigmDesignPatternImplementor综合症：-D

给定下面的类定义。如何决定存根方法应该是静态的还是非静态的？

这有点啰嗦，但也是一个非常严肃的问题。jQuery 改变了 ajax 参数序列化如下：

jQuery 1.4 在 jQuery.param 中添加了对嵌套参数序列化的支持，使用 PHP 普及的方法，Ruby on Rails 支持。例如，{foo: ["bar", "baz"]} 将被序列化为“foo[]=bar&foo[]=baz”。

你抓到了吗？

你打电话给你的参数foo。如果 foo 的值是一个数组，jQuery 现在会将其重命名为foo[]你的背后。这样做的原因是因为一些 PHP 开发者和 Ruby 开发者希望 3rd 方 API 为他们重命名。

称我为老式的，但是当我用 key 将某些东西放入地图时x，我希望在x. 或者至少具有可选覆盖的默认行为。

甚至文档也同意我的观点：

如果 value 是一个数组，jQuery 使用相同的键序列化多个值，即 {foo:["bar1", "bar2"]} 变为 '&foo=bar1&foo=bar2'。

我是否认为这只是来自 jQuery 团队的错误判断？

我有List<Foo> getFoos ()从远程服务器获取数据并返回它的方法。

当然，用户不应该更改列表的项目数，因为他会得到与服务器上的数据不同步的数据（如果他想要更改项目数，他有特殊的方法，例如addFoo ()）。

第一种方法是返回数组并将方法的签名更改为Foo[] getFoos (). 但它在 java 中更常见，用户操作集合更方便，所以我将签名更改为List<Foo> getFoos (). 此方法总是返回

Collections.unmodifiableList (originalList)

因此，当用户尝试更改列表时，他会得到 RuntimeException。

类似情况下有没有关于api设计的推荐？

我正在研究 API，它应该提供对许多基于远程 Web 服务的资源的简单访问。

其中一些远程资源需要在交互之前传递特殊参数。例如，其中一个需要传递一对开发者的密钥，另一个需要一对密钥和唯一标识符。第三个根本不需要这些参数。我现在正在使用 3 项服务，但它们的数量可以扩大。

对于每个网络服务，我都有相应的 API 实现。问题是我不知道如何向我的 API 引入传递未知数量的未知含义的字符串的可能性。

我的一些建议：

1.

2.

其中 ServiceParams 是一个标记接口。在这种情况下，我将有一些这样的助手类：

优点：每个服务的有意义的参数名称。

缺点：如果我为第四项服务提供支持，那么用户将不得不更新工厂模块。在第一种情况下，用户只需下载新模块。

3.

优点：最容易使用。用户不需要做任何额外的动作（比如创建 ServiceParams 的属性）。

缺点：最不明显的方式。用户应该知道哪一组参数对应于他想要创建的服务。

4-6：

相同的变体，但参数不是传递给工厂方法，而是传递给服务实例（例如在它的 init() 方法中）。

优点：用户可以根据需要更改其服务的密钥，而无需创建同一服务的新实例。

缺点：方式比较复杂，利润值得商榷。

您更喜欢哪种变体？为什么？欢迎您的变体。

我正在修改我没有编写的使用 JavaMail 的代码，并且在理解 JavaMail API 的设计方式时遇到了一些麻烦。我有一种感觉，如果我理解了，我可以做得更好。

我们称之为：

那么为什么 Eclipse 会警告我：

是调用静态方法吗？

如果我不能使用该对象发送消息，为什么我会获得一个 Transport 对象并提供特定于它的设置？传输类甚至如何知道用于发送消息的服务器和其他设置？它工作正常，这很难相信。如果我为两个不同的服务器实例化了 Transport 对象会怎样？它怎么知道使用哪一个？

在写这个问题的过程中，我发现我真的应该打电话：

那么静态 Transport.send() 方法的目的是什么？这只是糟糕的设计，还是有这样的原因？

例如：

这仅在使用 a 时CertPathValidator使用。我看到两个重要的选项：

• 再次单例，但每个属性都有 getter 和 setter
• 包含与当前上下文相关的属性的对象：（ CertPathValidator.setValidatorProperties(..)它已经有一个 setter for PKIXParameters，这是一个好的开始，但它不包括所有内容）

一些原因可能是：

• 从命令行设置属性 - 从命令行到上面建议的类中的默认值的简单转换器将是微不足道的
• 允许不同的提供者提供额外的自定义属性——它们可以有public Map getProviderProperties()，甚至可以public Object ..使用强制转换。

我很好奇，因为这些属性并不总是在最显眼的地方，而且在使用 API 时不必看到它们，您必须先查看数十个谷歌结果（如果幸运的话）才能获得它们。因为——首先——你并不总是知道你在寻找什么。

我刚刚观察到的另一个致命缺点是这不是线程安全的。例如，如果两个线程想通过 ocsp 检查撤销，它们必须设置ocsp.responderURL属性.. 并且可能会覆盖彼此的设置。