问题标签 [api-design]

我们在结构如下的 REST 服务器上有一些资源：

• /someResources/foo
• /someResources/bar
• /someResources/baz

其中someResource是远处分布式对象的服务器表示。

我们希望通过在网络中查看它并更新服务器的缓存来告诉服务器“刷新”它对“分布式对象”的表示，即我们不能简单地放置新值。

什么是干净的 REST 方法？

a）是否发布到/refreshes/新的“刷新请求”？

b) 是 PUT（带有空白文档）http://ip/someResources吗？

c) 别的？

我喜欢（a），因为它会给我们一个 id 来识别和跟踪刷新命令，但担心我们创建了太多资源。有什么建议吗？

在 API 设计中，做这样的事情是否常见：

在 get 的主体中，这会调用填充集合的私有方法。所以我只向客户公开一个一致的对象。让我感到困惑的是，让类及其成员静态化是否正确？毕竟，我们正在返回一个对象，因此该类也是不可变的（我一直认为不可变的类应该是静态的？）。我知道静态并不暗示无国籍。我认为静态是否适合作为一个实体集中的任何事物（例如公司详细信息）？

谢谢

有一种方法Lookup<,>不在ILookup<,>：

为什么Enumerable.ToLookup<>()声明的返回类型是ILookup<,>尽管它似乎总是返回一个实例Lookup<,>？如果返回类型被声明为Lookup<,>，则上述方法可以在没有强制转换的情况下使用。

我正在观看本次讲座（http://www.youtube.com/watch?v=aAb7hSCtvGw&hl=nl），在大约 34 分钟时，提到了幻灯片上的一个要点，说明“非常仔细地记录状态空间”。

什么是状态空间？为什么我必须“非常仔细地”记录它？不幸的是，我现在发布的机器上没有声音，但是幻灯片本身对我的学习非常有用（如果有声音，它会更有帮助）。

谢谢

我正在为我正在编写的系统设计一个内部 API。API 设计中有哪些最佳实践需要考虑？

我喜欢使用脚本包含使用 Google Maps 的 API 的方式，但我很担心：

我的 api 是“半私有的”，也就是说，可以通过互联网访问，但应该允许数据的安全传输和某种身份验证。数据应该通过网络保持私有，一个消费者不应该能够获取另一个消费者的数据。

如何使用 SSL 和某种身份验证来确保数据安全，但仍可从纯 HTML 页面“水平”访问，而无需服务器端代理？我需要管理密钥吗？如何将密钥发布到服务器而不被拦截？我可以使用 OpenId（或其他一些 3rd-party 身份验证）来验证 api 用户，还是必须创建自己的身份验证机制？我一直在使用 Google，但找不到安全设计和部署 API 的好指南。

现在我正在使用 REST 和 AJAX 来使用它们，但是跨域调用是不可能的。任何帮助或正确方向的指针将不胜感激。

我正在考虑在 C# 中创建一个持久性集合（列表或其他），但我想不出一个好的 API。

我在Clojure 意义上使用“持久” ：持久列表是一个表现得好像它具有值语义而不是引用语义的列表，但不会产生复制大值类型的开销。持久集合使用写时复制来共享内部结构。伪代码：

Clojure 使用这样的数据结构，但在 Clojure 中，所有数据结构都是不可变的。执行所有写时复制的工作都会产生一些开销，因此 Clojure 提供了一种临时数据结构形式的解决方法，如果您确定不与其他任何人共享数据结构，您可以使用该解决方法。如果您只有对数据结构的引用，为什么不直接对其进行变异，而不是经历所有的写时复制开销。

获得这种效率增益的一种方法是在您的数据结构上保持引用计数（尽管我不认为 Clojure 以这种方式工作）。如果 refcount 为 1，那么您将持有唯一的引用，因此会破坏性地进行更新。如果引用计数较高，则其他人也持有对它的引用，该引用应该表现得像值类型，因此请执行写时复制以免打扰其他引用者。

在这种数据结构的 API 中，可能会暴露引用计数，这会严重降低 API 的可用性，或者不能进行引用计数，如果每个操作都是 COW，则会导致不必要的写时复制开销，或者 API失去它的价值类型行为，用户必须管理何时手动执行 COW。

如果 C# 有结构的复制构造函数，这将是可能的。可以定义一个包含对真实数据结构的引用的结构，并在结构的复制构造函数和析构函数中执行所有 incref()/decref() 调用。

有没有办法在 C# 中自动执行引用计数或结构复制构造函数之类的操作，而不会打扰 API 用户？

编辑：

• 为了清楚起见，我只是在询问 API。Clojure 已经有一个用 Java 编写的实现。
• 当然可以通过使用一个结构来创建这样一个接口，该结构引用了在每个操作中都被 COW 处理的真实集合。引用计数的使用将是避免不必要的 COWing 的优化，但显然对于理智的 API 是不可能的。

JAX-RS 和 JAX-WS 非常适合生成 API。但是，它们根本没有解决向后兼容性的问题。

为了避免在 API 引入新功能时破坏旧客户端，您基本上必须接受并提供与以前完全相同的输入和输出格式；许多 XML 和 JSON 解析器似乎很适合，如果他们发现一个没有映射到任何东西的字段，或者有错误的类型。

一些 JSON 库，例如 Jackson 和 Gson，提供了一个功能，您可以根据运行时设置为给定对象指定不同的输入/输出表示，这似乎是在许多情况下处理版本控制的合适方法。这使得可以通过注释添加和删除的字段来提供向后兼容性，以便它们仅根据客户端使用的 API 版本出现。

迄今为止，我发现 JAXB 和任何其他 XML 数据绑定库都没有很好地支持这个概念，更不用说能够为 JSON 和 XML 重用相同的注释。将它添加到 JAXB-RI 或 EclipseLink Moxy 似乎是可能的，但令人生畏。

版本控制的另一种方法似乎是对所有已更改的类进行版本控制，通常是在每次发布 API 时创建一个新包，并在新包中复制所有修改的 DTO、服务和资源类，以便所有类型信息针对绑定和调度系统进行了版本控制。这种方法对我来说似乎更费力。

我的问题是：您如何设计您的 Java API 提供程序以实现向后兼容性？什么有效，什么无效？

非常感谢有关该主题的案例研究或博客文章的链接；我做了一些谷歌搜索，但没有找到太多关于这个的讨论。

我有一个包含 Mercurial 命令行客户端的类库。

我的目的是实现对所有内置命令的支持，但除此之外，还有大量的扩展。

所以我需要使我的库可扩展，因为我和其他人都可以添加对扩展的支持。我计划添加对一些更流行和典型的扩展的支持（至少有不少与 Mercurial 捆绑在一起的），但我仍然希望能够从外部扩展它。

目前，命令的语法如下所示：

然而，这并不适合扩展，程序员不会觉得扩展只是一部分。

例如，假设我公开了一个公共的附加命令行参数集合，我可以手动执行此操作：

对我来说似乎没有简单的方法来添加额外的扩展，使其可以设置为对象初始化程序的一部分。

我一直在考虑添加或切换到流畅的界面语法。在这种情况下，您可以编写如下内容：

但是，我看到人们不喜欢流畅的界面，他们觉得它们变得太健谈了。

我还有什么其他选择？

我想要的，基本上：

• 一种常见的语法风格
  • 对于两个内置的东西
  • 以及我的图书馆用户添加的扩展

我设想我的库的用户将通过添加新类和扩展方法来扩展它以获得智能感知支持，但扩展方法不能用于对象初始化程序，这意味着所有扩展看起来都是事后才想到的。那不是我想要的。

欢迎任何想法。

我正在用 C# 设计一个 API，我需要的一个功能是：

其中 ChildType 定义为：

它应该是不言自明的，但本质上，它将创建相关对象的子对象，并且子对象包含的值类型将是字符串或基于枚举值的双精度值。

枚举是公开的ChildType，因此，我认为 API 的用户可以访问。

我担心的是某些语言无法理解签名中的枚举，并且无法针对此 API 进行编程。这是需要担心的事情，还是我的恐惧没有根据？