REST and SOAP

REST (Representational State Transfer) and SOAP (Simple Object Access Protocol) represent two different styles for implementing services. Technically, REST is an architectural pattern built with simple verbs that overlay well on HTTP. While REST architectural principles could be applied with protocols other than HTTP, in practice REST implementations are used in conjunction with HTTP. SOAP is an XML-based messaging protocol that can be used with any communication protocol, including HTTP.

The main difference between these two approaches is the way that the service state is maintained. With SOAP, movement through different states can be accomplished through interaction with a single service endpoint, which may encapsulate and provide access to many operations and message types. With REST, a limited set of operations is allowed, and these operations are applied to resources represented and addressable by URIs (HTTP addresses). The messages capture the current or required state of the resource. REST works well with Web applications, so you can take advantage of HTTP support for non-XML MIME types or streaming content from a service request. Service consumers navigating through REST resources interact with URIs in the same way as a human user might navigate through and interact with Web pages.

While both REST and SOAP can be used with most service implementations, the REST approach is often better suited for publicly accessible services or cases where a service can be accessed by unknown consumers. SOAP is much better suited to implementing a range of procedural interactions, such as an interface between layers of an application. With SOAP, you are not restricted to HTTP. The WS-* standards, which can be utilized in SOAP, provide a standard and therefore interoperable method of dealing with common messaging issues such as security, transactions, addressing, and reliability. REST can also provide the same type of functionality, but you must often create a custom mechanism because only a few standards currently exist for these areas.

In general, same principles can be used when designing SOAP based interactions as you do for stateless REST interactions. Both approaches exchange data (the payload) using verbs. In the case of SOAP, the set of verbs is open ended and is defined by the service endpoint. In the case of REST, the set of verbs is constrained to preset verbs that mirror the HTTP protocol. Guidelines when choosing between REST and SOAP:

• SOAP is a protocol that provides a basic messaging framework upon which abstract layers can be built, and is commonly used as an RPC framework that passes calls and responses over networks using XML-formatted messages. 
• SOAP handles issues such as security and addressing through its internal protocol implementation, but requires a SOAP stack to be available.
• REST is a technique that can utilize other protocols, such as JavaScript Object Notation (JSON), the Atom publishing protocol, and custom Plain Old XML (POX) formats.
• REST exposes an application and data as a state machine, not just a service endpoint. It allows standard HTTP calls such as GET and PUT to be used to query and modify the state of the system. REST is stateless by nature, meaning that each individual request sent from the client to the server must contain all of the information necessary to understand the request since the server does not store the session state data.

Design Considerations for REST
REST represents an architecture style for distributed systems, and is designed to reduce complexity by dividing a system into resources. The resources and the operations supported by a resource are represented and exposed as a set of URIs over the HTTP protocol. Consider the following guidelines when designing REST resources:

• Identify and categorize resources that will be available to clients.
• Choose an approach for resource representation. A good practice would be to use meaningful names for REST starting points and unique identifiers for specific resource instances. For example, http://www.contoso.com/employee/ represents an employee starting point. http://www.contoso.com/employee/smithah01 uses an employee ID to indicate a specific employee.
• Decide if multiple representations should be supported for different resources. For example, you can decide if the resource should support an XML, Atom, or JSON format and make it part of the resource request. A resource could be exposed as both (for example, http://www.contoso.com/example.atom and http://www.contoso.com/example.json).
• Decide if multiple views should be supported for different resources. For example, decide if the resource should support GET and POST operations, or only GET operations. Avoid overuse of POST operations if possible, and avoid putting actions in the URI.
• Do not implement the maintenance of user session state within a service, and do not attempt to use hypertext (such as hidden controls in Web pages) to manage state. For example, when users submit requests such as adding an item to a shopping cart, store the data in a persistent state store such as a database.

Design Considerations for SOAP
SOAP is a message-based protocol that is used to implement the message layer of a service. The message is composed of an envelope that contains a header and body. The header can be used to provide information that is external to the operation being performed by the service. For example, a header may contain security, transaction, or routing information. The body contains contracts, in the form of XML schemas, which are used to implement the service. Consider the following guidelines when designing SOAP messages:

• Determine how you will handle faults and errors, and how you will return appropriate error information to clients.
• Define the schemas for the operations that can be performed by a service, the data structures passed with a service request, and the errors or faults that can be returned from a service request.
• Choose the appropriate security model for your services. Avoid using complex types in message schemas. Try to use only simple types to maximize interoperability.