REST API vs SOAP API technology

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


In: Root » Internet » APIs and Web Feeds » REST API vs SOAP API technology

Dutch French Spanish Portuguese Italian German Japanese Chinese Korean Russian Arabic Bookmark and Share this Article

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 your maintenance, support, and documentation time for the life of the API.

Both API methods have already been introduced at length; this section concentrates on differences to keep in mind when developing an API.

REST APIs

When receiving a REST request, the information will come in via GET. As such, all the information will need to be URL-encoded during transmission; you will likely want to decode it before subjecting it to any further processing (the exception being usernames and passwords, which are generally processed as-is). Different request types should be addressed to different endpoints (URLs); if you want to use a single script to handle all requests, you can either present it to developers in that manner (all requests go to a single endpoint), or configure your web server to map many endpoints to a single script. I would generally suggest the latter; it's inline with the specification and it allows you to make changes later without affecting the external interfaces developers use.

Consider allowing developers to use a web interface to make requests against the API. This can be of great use when attempting to diagnose a problem; developers will be able to quickly determine if the problem is the request or their code. The more tools you can provide to developers in terms of diagnostics, the easier it will be to develop for your site.

SOAP APIs

When the SOAP request comes in, it should first be checked to ensure that it conforms to the format specified by your WSDL document. If you are using a tool such as NuSOAP, this is done for you. In fact, most SOAP APIs use some framework that takes care of a lot of the grunt work when handling the requests. SOAP APIs use a single endpoint for all requests (as a general rule, some large APIs separate disparate functions onto different endpoints), and as a result you will likely either have a large script at that point, or lots of require() calls executed depending on the particular call.

Consider allowing developers to use a web interface where they can paste entire request documents onto a form, and run them against your server. Speaking from direct experience, having something like this available is of great use to developers when trying to diagnose a problem. Providing scripts or functions on your site to allow developers to create requests manually will also be of assistance to developers not using a SOAP framework.

Disclaimer

1) E-articles 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 infringement, please read the terms of service and contact us to investigate the problem.
2) E-articles is not responsible for inaccuracies, falsehoods, or any other types of misinformation this article 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.

link to this article