Question

我开始设计一个基于网络的API，第一个问题 - 用户将如何与之互动 - 让我感到茫然。这是一个API，它只会被我们公司内的其他人使用，并且会被具有一定编程知识的人使用，所以在所有方面都有一点余地，而且对于非专业人士来说，它不够简单

我是否应该拥有一个网址并将所有信息作为查询参数传递：

http://hostname/api/v1?func=getZipCode&state=Ohio&city=Toledo&street='100 Cherry Street'

或者RESTful：

http://hostname/api/v1/getZipCode/Ohio/Toledo/100 Cherry Street

或者SOAP是要走的路：

POST /api/v1 HTTP/1.1

<?xml version="1.0"?>
<soap:Envelope>
<soap:Body xmlns:m="http://hostname/api/v1/wsdl">
  <m:getZipCode>        
    <m:state>Ohio</m:state>
    <m:city>Toledo</m:city>
    <m:street>100 Cherry Street</m:street>
  </m:getZipCode>
</soap:Body>
</soap:Envelope>

每种方法的（dis）优势是什么？

Answer 1

你的“REST”实例根本与REST无关，它只是一个漂亮的URI。检查StackOverflow上的其他问题，解释REST是什么，或者阅读Fielding's dissertation on REST作为权威来源。

由于URI和资源之间的耦合最小化，REST拥有的SOAP和RPC的一个优点是API不那么脆弱。在REST中，您通过超文本导航资源 - 每个资源表示响应都包含相关资源的URI，因此您在已发布的API中需要的唯一URI是单个入口点。在RPC中，您通常会在API中包含所有可能的URI，这是一个巨大的耦合和过度脆弱。服务器应该能够管理自己的URI空间，就像在REST中一样。

在SOAP中，您只需使用一个URI来进行POST即可。 POST请求不会被缓存，因此这是一个巨大的缺点。 SOAP并不像REST那样尝试适应HTTP堆栈 - 它只是使用HTTP作为隧道。

Answer 2

您的客户使用哪种语言？他们有什么工具来使用您的服务？我最关注的是选择在他们的编程环境中得到很好支持的东西。

在可消费性方面，我在REST和SOAP方面取得了很大成功。我的Java实现的服务已经被.NET开发人员用尽了很多技术工作。

SOAP方法是整个WesbServices的一部分，它的WS- *形式：对于细粒度的安全性，异步传递，事务和各种其他好东西，它有各种变体和扩展。如果将来可能出现那些更重要的要求，我会选择SOAP。

如果您的消费者更有可能成为浏览器中的AJAX客户端，则使用JSON有效负载的REST可能非常适合。

总结，关注客户的需求和能力。让他们的生活变得轻松。

Answer 3

在研究上述替代方案的细节之前，我会评估企业中的现有标准。当然，如果没有，那么你可以根据自己的需求和偏好自由选择。

但是你不太可能在真空中构建系统API。因此，可能大多数决策已经被用于采用一种或多种方法，您只需要检查这些决策，了解他们如何以及为什么制定这些决策，使用您构建的系统分析他们的关系和依赖关系。在此之后，您的选择应该变得更加不确定，因为您不再仅仅设计API - 您现在正在设计作为系统一部分的解决方案。

更新：询问您的未来和潜在客户已经使用的内容。他们不想接受另一个标准，如果现有的标准符合您的需求，那就去吧。

Answer 4

如果您想成为RESTful，请不要将某些服务版本（如“v1”）放入URI中。关于版本化REST Web服务的一些想法，由Peter Williams here和here描述。

Answer 5

SOAP：

优点：

在大多数语言中，使用WSDL并将其转换为原始代码相当容易。这也为您提供了基本数据对象，这也是一个好处。
从java和其他一些语言生成WSDL也相对容易

缺点：

有时候工作很痛苦。
这可能非常冗长。您最终可以传输比实际内容更多的标记。

获取网址：

优点：

以大多数语言编写服务器和服务器非常容易。

缺点：

您如何将数据返回给用户？他们是否必须解析一些数据格式？

的RESTful

优点：

这些日子是“性感的”
有些库可以轻松输出多种格式的数据

缺点：

根据语言编写可能会很痛苦。
除非你真的要把它变成“纯粹的REST”，否则它可能不值得付出努力（甚至可能是值得怀疑的）

将接口编写到Web服务API

5 个答案:

SOAP：

获取网址：

的RESTful