最佳实践以及如何在客户端的 C# 包装器中支持不同版本的 REST API答案

【问题标题】：Best Practices and How to support different versions of REST APIs in C# wrapper on client-side最佳实践以及如何在客户端的 C# 包装器中支持不同版本的 REST API
【发布时间】：2012-09-22 12:12:15
【问题描述】：

我编写了一个 C# 包装器来支持我们公司项目的 REST API。但是，这些 API 现在正在发生变化 - 在 URL（可能会在 URL 中引入版本号）和它期望并返回的数据对象方面。

我想知道在我的 c# 包装器中支持不同版本的 REST API 的最佳做法是什么。

我应该怎么做 - 在代码设计和类定义方面 - 以便一个包装器可以与不同版本的 API 无缝工作 - 它也应该是可扩展的 - 以便将来任何新版本的 API 也可以很容易得到支持。

我编写的 c# 包装器正在使用我们的 Web 服务 API。我已经在使用 RestSharp 客户端在 c# 包装器中使用我们的 Web 服务 API。

【问题讨论】：

请澄清 - 您是在使用 REST API，还是在生产它们？如果生产它们，您使用什么框架（WebAPI、ServiceStack、WCF）？如果使用它们，请发布您当前如何使用的示例代码。谢谢。
另外，虽然它可能无法直接回答您关于版本控制的问题，但您应该考虑使用 RestSharp 进行消费restsharp.org
我编写的 c# 包装器正在使用我们的 Web 服务 API。我已经在使用 RestSharp 客户端在 c# 包装器中使用我们的 Web 服务 API。

标签： c# api rest version wrapper

【解决方案1】：

设置 API 版本，将当前版本保持为版本 1，然后添加类似 v2 的版本

/current/api?id=x....
/version2/api?id=x...

这允许您更新您的 api 以支持新功能，然后您可以为过时的版本设置日落计划。

这样您就可以让您的客户转移到您的新系统，而不会发生紧急情况。

【讨论】：

他问的是客户端，而不是服务器。

【解决方案2】：

您的要求有点奇怪。让我重申一下你所说的：

1) 您的组织中存在同一服务的多个版本。也许它们像 Bob 建议的那样建立，/current/api... /v1/api... /v2/api... 等等。或者可能是其他一些模式。

2) 您希望单个 C# 库能够识别每个不同的版本。

奇怪的是第二部分。通常，客户端库仅针对特定版本。服务器有责任确保新版本的服务要么向后兼容旧版本，要么在新的 url 上隔离。

问问自己这个问题 - 如果您要继续构建这个库，该库可以识别同一服务的多个版本，您的库的使用者会如何看待它？他们是否必须明确告诉您要使用哪个版本？这不是我期望必须意识到的问题。

var client = new MyClient();
client.DoSomething();   // Makes sense    
client.DoSomethingV2(); // Huh?

【讨论】：

为较新版本的每个 API 创建新函数会很困难 - 因为有将近 160 个 API。我想让设计通用，这样我就可以使用相同的功能（因为端点没有改变）来返回 V1 DTO 或 V2 DTO
这会破坏与任何未更新客户端的兼容性。您应该对服务器端进行版本控制，而不是客户端。
看看这篇文章：mnot.net/blog/2011/10/25/web_api_versioning_smackdown 他确实谈到永远不要破坏客户，这是我的主要观点。他还反对使用 URI 作为版本控制的手段，并提出了两种选择：1）将客户端的版本作为请求标头的一部分并确保服务器理解所有版本，或 2）通过 HATEOAS 方法自我发现服务.我不确定 WebAPI 是否可以干净地执行 HATEOAS，所以我会选择第一个选项。无论哪种方式，客户端一次只应该知道一个版本。
我同意客户应该只知道一个版本。此外，我们在 URL 中使用版本号。此外，版本号、URL 在两个版本中都是相同的 - 只是返回不同的对象。现在，我的 API 包装器也用于 API 的内部测试。所以，我想设计包装器，这样我就可以调用任何版本的 API，并测试 API 的向后兼容性以及使用相同的包装器。