规划你的WebAPI – 安全


译自“Professional Web APIs with PHP: eBay,
Google, PayPal, Amazon, FedEx, Plus Web Feeds” (chapter 12)


你一定听过这样一句话“失败的计划是必定失败(Fail to plan, and you plan to fail.”对WebAPI来说,在开始一切工作之前的规划尤为重要,因为他不仅会影响到实现难度,同时会让那些使用API的开发者痛苦不堪。

Continue reading “规划你的WebAPI – 安全”

[zt]SOAP风格中 RPC与Document的区别

大部分 Web 服务都是围绕着远程过程调用而构建的,而 WSDL 规范允许另外一种 Web 服务体系结构:文档样式(document style)。在该体系结构中,整个文档在服务客户端和服务器之间进行交换。
在 WSDL规范中隐含着一个非常巧妙的转换开关,它可以将 Web 服务的 SOAP 绑定从远程过程调用转换成 pass-through 文档。在 SOAP 协议绑定中的样式属性可以包含这两个值中的一个:rpc或document。当属性被设定为文档样式时,客户端知道应该使用XML模式而不是远程过程调用约定。本文将提供对这个 WSDL 转换开关的说明,描述它的好处,并将解释应该何时使用 pass-through 文档。
首先,让我们简要地谈谈 WSDL 的一些要点,来理解这个巧妙的转换是如何发生的。 WSDL 是一项 XML 规范,它被用来描述Web服务以及对于到达端点(服务)的协议相关的需求。WSDL 用抽象术语来描述服务;通过可扩展的绑定定义,它能够为使用具体术语调用服务定义协议和数据格式规范。下面的语法是直接从 WSDL 规范中摘录出来的,展示了在绑定中所包含的可扩展性元素:

<wsdl:definitions …. >
    <wsdl:binding name=”nmtoken” type=”qname”> *
        <– extensibility element (1) –> *
        <wsdl:operation name=”nmtoken”> *
           <– extensibility element (2) –> *
           <wsdl:input name=”nmtoken”? > ?
               <– extensibility element (3) –>
           </wsdl:input>
           <wsdl:output name=”nmtoken”? > ?
               <– extensibility element (4) –> *
           </wsdl:output>
           <wsdl:fault name=”nmtoken”> *
               <– extensibility element (5) –> *
           </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>
</wsdl:definitions>
 
WSDL 规范通常描述三种绑定扩展HTTP GET/POST、MIME 以及 SOAP version 1.1。HTTP GET/POST 和 MIME 中定义的绑定扩展用来定义与标准的 Web 应用程序进行通信的需
求,这些应用程序可能返回(也可能不返回)XML 文档。在发送或返回 XML 文档时,HTTP GET/POST 绑定的扩展是隐式的文档样式。
SOAP 绑定扩展用来定义支持 SOAP 信封协议的服务。SOAP 信封是一种简单模式,它设计成能包含 XML 消息,提供特定于应用程序的消息头和消息体。SOAP 绑定的扩展使 WSDL 文档能够声明 SOAP 消息的需求,这样应用程序就能够与服务正确通信。SOAP 扩展允许将 SOAP 消息的样式声明为文档或 RPC。如果在soap:binding元素中声明了样式属性,那么该样式将成为所有没有显式声明的样式属性的soap:operation元素的缺省值。如果在soap:binding元素中没有声明样式属性,那么缺省的样式就是文档。下面是文档样式的显式声明:
Continue reading “[zt]SOAP风格中 RPC与Document的区别”

REST API vs. SOAP API

译自“Professional Web APIs with PHP: eBay,
Google, PayPal, Amazon, FedEx, Plus Web Feeds”

REST API
当处理REST请求时,因为信息是通过GET,所以,信息在传输过程中会进行URL编码(URL-encoded);当需要进一步处理时,首先要进行解码(唯一例外是用户名和密码)。不同的请求类型应该使用不同的endpoints(URLs);如果要以单独的脚本程序来处理所有的请求,你可以让所有的请求都指向同一个endpoint,或者配置web服务器来映射许多endpoints到同一个脚本。我建议用后一种方式;它符合规范同时允许你以后在不需要影响外部接口的情况下做修改。

允许程序员使用web接口来请求API – 在调试程序时将变得非常有用;程序员可以快速的判断问题源于请求本身还是代码。你可以提供给程序员的调试工具越多,你的网站也就越容易开发。

SOAP APIs
当处理SOAP请求时,首先要检查请求是否符合WSDL指定的格式。如果你使用诸如NuSOAP的工具,他可以帮你做到这一点。事实上,大多数SOAP API使用一个框架来处理许多低级的工作。 SOAP API使用单一endpoint接收所有请求(作为一个通用规则,一些大的API会根据功能来拆分到不同的endpoint),因此,或者是你有一个很大的脚本文件,或者是在每个功能点都调用很多required()方法。

允许程序员在使用web接口时可以粘贴整个请求文档到一个表单,然后发送到你的服务器。从直接的经验来看,有这样一个工具对程序员调试程序时是非常有用的。提供脚本或者函数从而让程序员可以手动创建请求对那些没有使用SOAP框架的程序员是很有帮助的。