问题标签 [api-design]

我目前的雇主使用第三方托管的 CRM 提供商，我们在两个系统之间有一个相当复杂的集成层。CRM 提供商的功能之一是让开发人员以类似 Java 的语言编写业务逻辑，并在用户单击按钮或向系统提交新帐户等事件时触发验证和/或业务逻辑。

我们使用的一项功能是让在托管提供商上运行的业务代码调用我们托管的 Web 服务。典型的例子是销售代表输入一个新的销售线索并点击一个按钮来 ping 我们的系统，看看我们是否可以根据电子邮件地址、公司/名字/姓氏等识别新的销售线索，如果可以，返回代表该个人的内部 GUID。这一切对我们来说都很好，但是我们一次又一次地试图建立一个理智的开发环境来工作。

因此，虽然我们的用例有点细微差别，但这通常适用于任何构建 API 以供第三方使用的开发公司： 当您构建供外部使用的 API 时，设计开发管道和环境时有哪些最佳实践世界？

在我们的办公室，我们所有的开发人员都在防火墙后面，因此正在进行的代码不会受到外部世界的影响，在我们的例子中是 CRM 提供商。我们可以在防火墙上戳洞，但从安全表面区域的角度来看，这并不理想。特别是如果需要在类似 DMZ 的区域中的开发人员数量很高。我们目前正在 DMZ 中尝试单台开发机器，然后根据需要进行远程处理以进行开发工作，但如果多个开发人员需要该机器，就会产生资源稀缺问题，更不用说他们进行潜在的冲突更改（例如不同的分支）。

我们考虑过通过为这些服务构建虚假客户端来模拟/伪造传入请求，但这是构建功能集的一个相当大的开销（尽管它本质上确实增强了我们 API 的可测试性）。这也不能排除这样一个事实，即有时我们确实需要诊断/调试来自真实客户端本身的问题，而不是一些伪造的请求有效负载。

其他人在这些类型的场景中做了什么？在这个混搭时代，必须有很多人有开发 API 的经验——对于那里的人来说，哪些工作（和不工作）好？

我将为 Web 应用程序构建一个 API，并且我对人们可以提出的良好实践建议很感兴趣。

我已经计划对其进行版本控制（版本 1 只能控制系统的某些方面，版本 2 可以控制更多，但这可能需要更改执行身份验证的方式，这将与版本 1 不兼容），并且身份验证将不同于人们用于登录的标准用户名/密码（如果有人确实使用了恶意工具，它不会将其打开为完全模拟，只要 api 允许）。

有没有人有进一步的想法，或者您使用过的具有特别好的 API 的网站示例？

多年来，我经常遇到以下问题模式：

• 我正在为一个包编写复杂的代码，该包由一个独立的应用程序和一个人们可以在其他应用程序内部使用的核心库版本组成。

• 我们自己的应用程序和用户使用核心库创建的应用程序都可能以批处理模式（离线、脚本化、远程和/或从命令行）以及交互方式运行。

• 库/应用程序需要复杂且大量的运行时输入，并且可能存在各种类似错误的输出，包括严重错误消息、输入语法警告、状态消息和运行统计信息。请注意，这些都是附带的输出，而不是应用程序的主要目的，应用程序将在其他地方显示或保存并使用不同的方法。

• 如果以交互方式运行，其中一些（可能只有非常严重的）可能需要一个对话框；但如果在批处理模式下运行，它需要登录而不停止用户输入；如果作为库运行，客户端程序显然希望在错误发生时拦截和/或检查错误。

• 这一切都需要跨平台：Linux、Windows、OSX。我们希望解决方案在任何平台上都不奇怪。例如，输出到 stderr 对 Linux 来说很好，但在链接到 GUI 应用程序时不能在 Windows 上工作。

• 库的客户端程序可以创建主类的多个实例，如果客户端应用程序能够区分每个实例的单独错误流，那就太好了。

• 让我们假设每个人都同意库方法通过简单的调用（错误代码和/或严重性，然后类似于 printf 的参数给出错误消息）记录错误就足够了。有争议的部分是客户端应用程序如何记录或检索它。

多年来我已经多次这样做了，但从未对解决方案完全满意。此外，这种子问题实际上对用户来说并不是很重要（如果出现问题，他们希望查看错误日志，但他们并不真正关心我们实现它的技术），但这个话题让程序员们兴奋不已他们总是在这个细节上浪费过多的时间，而且永远不会很开心。

任何人都知道如何将此功能集成到 C++ API 中，或者是否有公认的范例或良好的开源解决方案（不是 GPL，请，我想要一个可以在商业封闭应用程序和 OSS 中使用的解决方案项目）？

关于得墨忒耳法则的维基百科文章说：

该法可以简单地表述为“仅使用一个点”。

然而，流畅界面的简单示例可能如下所示：

那么这是否合二为一呢？

假设我有一个网站，其中包含一些可以从外部访问的信息。这些信息只需要由受人尊敬的客户更改。示例：Google Analytic 或 WordPress API 密钥。我怎样才能创建一个像这样工作的系统（无论编程语言如何）？

如果您有一个 API，并且您是英国开发人员，拥有高度国际化的受众，那么您的 API 应该是

或者

（以一个词为例。）

英国工程师通常对他们的“正确”拼写相当防御，但可以说美国拼写在国际市场上更“标准”。

我想问题是这有关系吗？其他语言环境的开发人员是否在为 GB 拼写而苦恼，还是通常很明显事物的含义？

应该都是美式英语吗？

我正在为 Netflix API 编写一个 .NET 包装器 API。

此时我可以选择将 URL 表示为字符串或 URI 对象。在我看来，两者都有很好的案例。

因此，如果您使用的是 API，您更喜欢哪一个？

今天的网站似乎有两类 API。

1. 允许扩展站点功能的 API，如 Facebook、Myspace 等。这些 API 似乎非常多样化。

2. 允许与现有站点功能（如 Twitter、Flickr 等）交互的 API。这些都声称是基于 REST 的，但实际上只是“HTTP 上的数据”。

如果您正在创建一个允许功能扩展和外部交互的网站，您会使用哪些现有 API 作为参考模型？

背景：

我正在我的大学上一门名为“软件约束”的课程。在第一堂课中，我们学习了如何构建好的 API。

我们得到的一个非常糟糕的 API 函数的一个很好的例子是public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds);C# 中的套接字。该函数接收 3 个套接字列表，并销毁它们，使用户必须克隆所有套接字，然后再将它们送入Select(). 它还有一个超时（以微秒为单位），它是一个 int，它设置服务器可以等待套接字的最长时间。这个限制是 +/-35 分钟（因为它是一个整数）。

问题：

1. 您如何将 API 定义为“坏”？
2. 您如何将 API 定义为“好”？

需要考虑的要点：

• 难以记住的函数名称。
• 难以理解的函数参数。
• 糟糕的文档。
• 一切都如此相互关联，以至于如果您需要更改 1 行代码，您实际上需要在其他地方更改数百行代码。
• 破坏其参数的函数。
• 由于“隐藏”的复杂性，可扩展性差。
• 用户/开发人员需要围绕 API 构建包装器，以便可以使用它。

我正在重新设计我们内部 ORM 工具的一部分，并且我想将 Field（代表数据库中的字段的类，如 CustomerFirstName）直接公开给最终开发人员。

所以这很容易实现，但是 API 变得有点难看，因为这个 Field 类以前在内部使用并且过于开放。例如，这只是一个小例子：IsDirty 属性不是只读的，这是最终开发人员不应该篡改的东西。

我考虑过可能创建两个接口，IPublicField 和 IPrivateField，并尝试让字段类来实现它们。但是，继续 IsDirty 示例，我不想要这样的东西：

...它只是有点难看，而且您仍然可以转换回 Field 类并进入非只读方法。我也不想引入单独的 setter 方法，因为这将是另一个我不想考虑的重大更改，并且还会与 API 的其他部分产生不一致。

我最终将 Field 类重命名为 InnerField，并围绕它创建了一个外观/包装器样式结构，如下所示：

这似乎工作得很好。在内部，InnerField 是适当开放的，我们可以在不影响最终开发人员的情况下自由地在未来使其更加开放，而在外部，Field 类提供了最终开发人员所需的简化、锁定工具。

因此，假设这是连贯的，我想知道您在这种情况下可能会如何进行，以及我的解决方案从外面看起来是否合理。

谢谢！