Building and designing web services and APIs requires that you first know what stacks you have to work with. Typically your options will always boil down to two: SOAP or REST?
What is REST?
REST is an architectural style made up of constraints: Client-Server, Stateless, Cache, Uniform Contract, Layered System and Code-on-Demand. All but Code-on-Demand are required.
*as defined by Roy Fieldings dissertation "Architectural Styles and the Design of Network-based Software Architectures".
The most fundamental requirement for REST is that there is an enforced separation of concerns: the client makes requests to resources via a shared contract and the server responds. In a REST architecture, the server is a passive listener.
All communication from client to server should be stateless. Each request from the client should contain all the necessary information for the server to process the request.
Responses from the server need to be explicitly labeled as cacheable or non-cacheable. This builds upon the previous two constraints. Since all requests must flow from client to server and have to be stateless, a cache component can be introduced that allows for reuse of server responses.
Clients can access server resources via a common set of methods, media types and resource identifiers. Being defined in parallel to HTTP 1.1, REST reuses HTTP for it's interface: HTTP actions, media types and URIs.
Layers can be added, removed, changed or reordered from the system. Each layer only knows about the layer they are interacting with and cannot "see" past that layer. A layer is typically a proxy server, firewall or facade server.
Code-on-Demand is the optional, and least used, constraint. This style lets the client request resources from the server that it does not inherently know how to process and receive the response plus code to process resource. This allows the server to offload some processing increasing its scalability but does have the drawback of requiring clients to trust the servers to execute arbitrary code.
What is SOAP?
In contrast to REST, SOAP is a protocol specification. Specifically it's a protocol for exchanging structured data through XML in three major parts: an envelope which defines the message, a set of rules for defining datatypes and rules for defining actions and their responses.
While REST has five architectural constraints, SOAP is typically defined by three characteristics: extensibility, transport neutrality and platform independence.
The SOAP protocol allow for arbitrary extensibility to handle concerns that are not addressed by the protocol itself. Namely security, addressing, discovery and transactions, to name a few.
Ordinarily you'll see SOAP being used over HTTP but SOAP can be used over any transport protocol such as TCP, SMTP, MSMQ or JMS.
Since SOAP defines the datatypes used and has metadata (as XML) stored about the messages, actions and responses it's quite easy for any platform to consume that metadata and work with SOAP endpoints.
Which one is right for me?
Example REST Use Case
Let's say you are trying to create the next great "140 character" microblog platform. You want your platform to have an API that allows developers to create apps that can create and delete posts, manage user preferences and find other users to follow. You want to do this with as little ceremony as possible but have the API available across many platforms and easily consumable by developers. REST makes it easy for you to write a very lightweight API that allows you to map those requests to HTTP verbs:
- POST new updates
- DELETE existing updates
- PUT user preferences
- GET other users.
Any system in the world that is capable of creating an HTTP request now has potential to access your next great microblog platform.
Example SOAP Use Case
Your have been hired to architect a healthcare portal. That health care portal is going to be doing a lot of B2B and system-to-system integration. Each call into the system needs to adhere to strict security requirements that have been standardized. Also, there are many dependencies in the messages that need to be spelled out and statically verified.
Since SOAP has platform-independent extensibility at its core and uses XML and XSD to define its messaging layer, both of those requirements can easily be handled.
- There are numerous XML verification tools and APIs that can be used to statically verify that the message adheres to SOAP Web Service Description
- Through the use of extensions like WS-Security, WS-Trust and WS-Federation you know that security is being handled via standard security tools and technologies.
Questions? Comments? Please leave a comment below or feel free to contact me on Twitter: @rrinaldi