Http 将接口写入web服务API

我开始设计一个基于web的API，第一个问题是用户如何与它交互，这让我不知所措。这是一个API，只供我们公司内的其他人使用，并且将由具有一些编程知识的人使用，因此在各个方面都有很大的回旋余地，对于外行来说，它并不需要足够简单

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

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

或是一些安静的东西：

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>

POST/api/v1 HTTP/1.1
俄亥俄州
托莱多
樱桃街100号

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

SOAP： 优点：

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

缺点：

• 有时和他一起工作是件很痛苦的事
• 它可能非常冗长。最终可能会传输比实际内容更多的标记

获取URL: 优点：

• 用大多数语言编写服务器和服务器非常容易

缺点：

• 如何将数据返回给用户？他们需要解析一些数据格式吗

宁静的 优点：

• 现在很“性感”
• 有些库可以轻松地以多种格式输出数据

缺点：

• 根据语言的不同，写作可能会很痛苦
• 除非你真的要让它成为“纯粹的休息”，否则它可能不值得付出努力（即使这样，它也值得怀疑）

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

就可消费性而言，我在REST和SOAP方面都取得了很好的成功。我的Java实现的服务在.NET开发人员使用时没有付出很大的技术努力

SOAP方法以WS-*的名义是整个WesbServices的一部分：它有各种变体和扩展，用于细粒度安全性、异步交付、事务和其他各种好东西。如果这些更重的需求在未来可能会出现，我会选择SOAP

如果您的用户更可能是浏览器中的AJAX客户端，那么REST with JSON有效负载可能非常适合

---

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

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

但不太可能在真空中构建系统API。因此，可能大多数决策都是为了采用一种或多种方法而做出的，您只需要回顾这些决策，了解它们是如何做出的以及为什么做出这些决策，分析它们与您构建的系统之间的关系和依赖关系。在此之后，您的选择应该变得不那么不确定，因为您不再只是设计API—您现在正在设计作为系统一部分的解决方案

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

您的“REST”示例实际上与REST无关，它只是一个漂亮的URI。检查StackOverflow上解释REST是什么的其他问题，或阅读权威来源

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

---

在SOAP中，您只需对发布到的所有内容使用一个URI。POST请求没有缓存，因此这是一个巨大的缺点。SOAP不像REST那样试图融入HTTP堆栈——它只是将HTTP用作隧道。

如果您想要RESTful，不要将“v1”之类的服务版本放入URI中。关于版本化REST Web服务的一些想法，如Peter Williams和所述。

请扩展您对REST的最后一个限制。什么是努力，为什么不值得？-1没有关于REST的有用信息。“获取URL”同样没用。对不起，Eric，但是您的比较非常缺乏真实信息。诚然，这个问题的措辞并不容易回答，但你的回答并没有增加价值。