将接口编写到Web服务API

Question

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

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

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关于REST的权威来源论文.

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

在SOAP中,您只需为POST所使用的所有内容使用一个URI.POST请求不会被缓存,因此这是一个巨大的缺点.SOAP不会像REST那样尝试适应HTTP堆栈 - 它只是使用HTTP作为隧道.