Note: I created this sample from a prompt, and decided to post it here for all to see.
SOAP and REST offer two potential interfaces for web APIs. Which should you use for your project?
SOAP, or Simple Object Access Protocol, is an XML-based protocol designed to simplify communication between web services. SOAP has three major characteristics:
- Extensibility through user-generated extensions tying into a base structure.
- Neutrality by operating over any transport protocol such as HTTP, SMTP, TCP, UDP, or JMS.
- Independence by allowing variable programming paradigms and structures.
A SOAP message is an ordinary XML document containing
- An envelope (required) that specifies it as a SOAP message.
- A header or headers (optional) that directs the receiver.
- A message (required) that contains the call and response information.
- A fault (optional) that provides information about errors that occurred while processing the message.
Applications related to billing, banking, navigation, transportation route calculations, booking a flight, and other cases benefit from a formal contract between the web service provider and its customers. The SOAP process is clearly defined, leaving no room for misinterpretation. Stateful operations ensure multiple chained operations act as one operation.
Operations that require long calculations, massive data, and creating results from the combination perform better with asynchronous communication. Since SOAP operates over any transport protocol, choose the best protocol to immediately return a pending result to a caller while other operations are triggered in the interim.
Security and authorization are part of the protocol, as SOAP uses the protocol’s existing features and does not require modifications.
REST, or Representational State Transfer, is an architectural style designed to be more lightweight than SOAP. It uses the six guiding constraints listed below to improve performance, scalability, simplicity, modifiability, visibility, portability, and reliability.
- Uniform interface: Fundamental to REST service design, a uniform interface allows each part of the architecture to evolve independently.
- Client-server: By decoupling user interface concerns from data storage concerns, components can change separately and scale more easily.
- Stateless: Each client request is self-contained with all necessary information; no information is kept on the server unless it is transferred to a database for authentication.
- Cacheable: Responses define themselves as cacheable or not, partially or completely eliminating some client-server interactions and improving scalability and performance.
- Layered system: Intermediary servers between the client and end server can help balance loads and share caching, improving scalability and enforcing security policies.
- Code on demand: Servers can also provide client-side scripting, transferring executable code that extends or customizes client functionality.
Since REST clearly separates client and server implementation, can return data in multiple formats (JSON, XML, etc.), and the stateless requests are self-contained, REST works well for open web applications. Mobile APIs benefit from reduced communication bandwith because REST objects are not required to fully map to the client and there is less metadata.
Use SOAP for enterprise applications and other formal applications that benefit from explicitly defined, stateful, formal contracts and allow for a large bandwidth. Asynchronous communication improves performance with large data sets. Examples include financial services, payment gateways, navigation, and telecommunication services.
Use REST for open web applications that evolve server and client requirements independently and focus most on open development, scalability, simplicity, and performance. Layered system with intermediary servers allow for additional scripts and load sharing. Examples include social networks and media services, web chat, and mobile.
|SOAP API||REST API|
|Data as resources (nouns). For example, “user” or “invoice”||Data as services (verbs). For example, “getUser” or “PayInvoice”|
|Multiple protocols (HTTP, SMTP, etc.)||Only HTTP protocol|
|Uses XML||Multiple formats (XML, HTTP, JSON, and URI).|
|Explicitly defined architecture.||Decoupled client and server relationship.|
|Stateful operations keep track of progress.||Stateless requests are self-contained.|
|Common uses: enterprise-level, financial services, payment gateways||Common uses: web-based, social media and networks, web chat, mobile|