Introduction to Web APIs ~ REST vs SOAP

written by: Emanuela Hedrick; article published: year 2006, month 08;



In: Categories » Internet » APIs and Web Feeds » Introduction to Web APIs ~ REST vs SOAP

When interacting with web services, generally the choice of which method to use will be made for you. The majority of services operate in either REST or SOAP, not both (Amazon is a notable exception to this rule). When given the choice, however, there are several points to consider:

  • Overhead — REST requests are relatively slim. SOAP requests, on the other hand, contain a lot of additional information, which can really add up.

  • Transparency — With REST requests (even when completed over HTTPS), all request information is sent in the clear; with SOAP only the end point (URL) is visible. This may sound like a clear-cut win for SOAP, but not quite. When requests go in the clear, they can easily be monitored by the relevant IT departments and screened by firewalls. REST requests can also be easily cached (when this is marked as allowable by the server) by existing infrastructure, reducing server load and bandwidth costs.

  • Ease of use — Many developers have indicated a preference to develop for REST servers, because the requests can be quickly generated without all the extra encapsulation required by SOAP. Amazon, for example (offering both REST and SOAP interfaces), has 85 percent of its requests occur over REST.

  • Service definition — SOAP services are defined by Web Services Description Language (WSDL) files, which contain all the information required to make a request. In fact, generic SOAP clients are available that will allow you to make any request provided by a service given nothing but the address of the WSDL file. There is no equivalent for REST services.

  • Encapsulation — SOAP requests are encapsulated within an XML envelope. The body of the request itself is then again encapsulated within a body element. The addition of namespacing within the document goes further to clearly define exactly what each element is describing. There are several excellent tools out there to assist document creation, which can take the tedium out of creating these longer requests.

Overall, there is no clear winner (if there was, I wouldn't need to introduce both). The choice will depend on the particular application and the tools available to build it. Generally speaking, when given the choice, I prefer to use SOAP in my web service communications. I feel that the service definition and encapsulation provided by SOAP outweighs the additional overhead and lack of protocol-level transparency.

Note 

One other common web service API is XML-RPC. Although XML-RPC is quite simple to learn and use, it lacks the features of SOAP while retaining a much higher overhead than REST. Therefore, depending on your purposes, choosing REST or SOAP would almost always be a better choice.

legal disclaimer

1) Our website is not responsible for the information contained by this article as well for any and all copyright infringements by authors and writers. E-articles is a free information resource. If you suspect this article for any copyright infringements, please read the Terms of service and contact us to investigate the problem.
2) The E-articles directory team is not responsible for inaccuracies, falsehoods, or any other types of misinformation this tutorial may contain and will not be liable for any loss or damage suffered by a user through the user's reliance on the information gained here. Please read the Terms of service

Useful tools and features

Translate this article to...    Send this article to you or to a friend

Link to this article from your page   
If you like this article (tutorial), please link to it from your web page using the information above. Linking to this page, this is the only way to help us improve our service, the same time providing your visitors with a way to improve their online experience.

related articles

1. REST API vs SOAP API technology
The two primary architectures for APIs are REST and SOAP. When creating your API, you really have three options: REST, SOAP, or both. REST APIs are known for being easy and quick to develop for, but the entire request is sent in the clear regardless of the type of encryption used. SOAP APIs are more complex, requiring more effort to generate the response and handle the request, but allow for greater flexibility by adding namespace support. Providing APIs of both types may sound like an attractive option, but keep in mind that it will double ...

2. Advantages and Disadvantages of SSL ~ API related
Configuring your web server to present the API over an SSL connection adds protection for both the request and response bodies, while requiring little to no additional coding for the API. Remember that the use of a server certificate only authenticates the server for the client, it does nothing to identify the client itself. It is best used layered with one of the previous two examples. Advantages: Encryption — Both request and response bodies are protected from intermediate prying eyes. ...

3. How SOAP Works
A SOAP request will involve creating and populating a request envelope, which contains all the required information (as specified by the WSDL document), transmitting that envelope to the API server, and handling the response. A SOAP request generally contains all of the following elements: SOAP Envelope — With namespace inclusions. SOAP Body — Possibly defining additional namespaces. Desired Action — How the desired action is represented will depen...

4. Why Do You Need to Produce Feeds
Feeds have several advantages, primarily related to consumption, over traditional HTML formats. Many desktop applications are devoted to reading feeds at regular intervals, and many of the new batch of web browsers include features for reading feeds. These free the user from manually checking various sources (websites) for new information. Instead, the automated tool checks the subscribed feeds every few minutes and presents them to the user (usually organized in a user-configurable manner). The standard and predictable format makes this a m...

5. How REST Works
Generally speaking, a REST request will involve sending a request to a special URL (similar to what you would see after filling out a form using the GET method), then receiving an XML document containing the server's response. The XML response is then parsed, and the desired information is extracted and acted upon. Each REST request generally has several common elements: Endpoint URL — The full address for the desired script. A REST service might have only a single script that handles all request type...

6. How to implement the REST technology
There are two sides to this tale, the first is how to generate legitimate REST requests, and the second is how to handle the responses correctly. Generating Requests When it comes to generating the request, you have three main options. First, you can generate the request manually, using PHP's header functions. This gives you complete flexibility in generating the request, but does involve the most coding. Second, you can use one of PHP's built-in request functions such as file_get_contents() or file()/fopen(), fread(...

7. Important Considerations When Using Feeds
XML feeds provide a great resource of information, but their use is not without its own special considerations. Security and legal concerns go hand in hand whether you are producing or consuming feeds. Consider if you will the implications of going away for the weekend, only to discover that your aggregator has been attacked, your site is now displaying wildly inaccurate information provided by the attacker, and your legal department is fielding not-so-nice phone calls regarding the current content of your homepage. Also consider how often...

8. Advantages and Disadvantages of Client Side Certificates
The API server can generate a certificate and provide it to the client via a secure channel before any requests are made. This certificate is then used in the authentication process; this confirms the identity of both the client and server before requests are made. Although this method provides the greatest level of security (barring a dedicated VPN connection, which won't be covered here), it also has the most strenuous requirements on both sides: not all modules (say, NuSOAP) can handle client-side certificates. Advantages:...

9. What are Feeds ~ RSS and ATOM Feed Specifications
You can think of feeds as small modules of information that can be plugged into existing websites, consumed by clients on their desktop, or consumed by aggregators to be presented by users with other feeds. Aggregators also offer searching functionality to users, allowing new users to locate your site and feed (a great reason to provide a feed in the first place). Websites such as Yahoo! produce web feeds. Software that downloads and uses feeds is said to consume or aggregate feeds. Sites such ...

10. Common API Performance Techniques
Websites are designed to be accessed by individuals, and as such tend to rely on the relatively slow speed of the user to avoid any performance bottlenecks. This technique fails miserably with APIs because they are going to be consumed by other servers with high-speed connections, often designed only with their own performance in mind (they won't cache your responses for you, and will instead make exactly the same request time and time again). Designing your API with performance in mind can help keep the server fast even when many req...