About
Web services provide a common ground for web applications to communicate. Exposing your web applications encourages use (e.g. FourSquare) and fosters creativity (e.g. Google Maps mash-ups). The W3C recognises two typesof web services: REST-complaint and arbitrary (e.g. SOAP).
REST
REpresentational State Transfer (REST) is a style of software architecture (not implementation) that defines behaviour between a client and server — most famously adopted by (but not limited to) the web.
Representations (i.e. actual information) are transferred by resources (i.e. sources of information, endpoints) identified by global identifiers (e.g. web address) over a standardised interface (e.g. HTTP), which passes through network components and connectors (e.g. servers). Key goals of REST are performance, scalability, simplicity, modifiability, visibility, portability, and reliability. To be considered RESTful the following architecture constraints must be met:
- Decoupled client and server
- Stateless
- Cacheable (implicitly or explicitly specified by the response)
- Layered (client unaware of intermediary servers e.g. load balancer, firewall, proxy)
- Optional code on demand (extend client functionality with executable code e.g. JavaScript to a browser)
- Generic interface:
- Resources are identified on request and return the corresponding representation
- Existing protocol features are adopted (e.g. HTTP response codes)
- Responses contain the information on how they are processed (e.g. MIME types, cacheability)
- Responses contain the links to modify the resource on the server (e.g. URI to delete), provided it has permission to do so
- Responses contain the links for further states (i.e. other resources). A client cannot assume any resources outside the initial entry point.
REST principles applied to web services implemented over HTTP must:
- Contain a base URI (e.g. http://api.example.com/v1/resources/)
- Support MIME types (e.g. JSON, XML, YAML)
- Support operations using HTTP methods (i.e. PUT, POST, GET, DELETE)
- Hypertext driven (i.e. linking to other resources), also referred to as HATEOS (Hypertext As The Engine of Application State).
HATEOS (Hypermedia As The Engine Of Application State = returned hyperlinks) pros and cons:
- Flexibility to change resource URLs +1
- Extensible (i.e. future proof) +1
- No documentation required +1
- If documentation is provided, it is subject to change without notice -1
- More responsibility and complexity for API consumers to discover URLs, which makes it slower to harder to adopt — especially if OAuth is involved. Also does not respect Tesler’s Law -1
- Less efficient because clients must make the same calls to discover the same URLs (although caching helps) -1
- In reality, the web is RESTful but people often bookmark pages to avoid re-discovering URLs -1
Many web services
claim to be RESTful, but do not implement all the REST constraints (almost always ignoring HATEOS). Such web services can be
considered RESTish and I’m going to go ‘out on a limb’ and estimate that 95% of all claimed services are not RESTful. This makes REST creator, Roy Fielding,
want to yell at you.
Examples:
{
home:{
users:{
a:{
href:'https://api.example.com/v1/users'
}
},
dogs:{
a:{
href:'https://api.example.com/v1/dogs'
}
}
}
}
https://api.example.com/v1/users
{
users:{
id:'jsmith',
name:'John Smith',
dogs:{
dog:{
id:'fido',
name:'Fido',
a:{
href:'https://api.example.com/v1/users/jsmith/dogs/fido'
}
}
}
}
}
https://api.example.com/v1/users/jsmith/dogs/fido
{
dog:{
id:'fido',
name:'Fido'
}
}
SOAP
Simple Object Access Protocol (SOAP) is an XML-based protocol that reduces HTTP (and other protocols) to the role of simple transport mechanism.
The protocol consists of an envelope (what the message is and how to process it), encoding rules (datatypes), and a convention for representing procedure calls and responses. SOAP consists of several layers (e.g. message exchange patterns) and was developed by Microsoft as a successor to XML-RPC.
The key goals of SOAP are extensibility (i.e. extensions), neutrality (any transport protocol), and independencefrom any programming model.
Examples:
Request
POST /Users HTTP/1.1
Host: api.example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "Get-Users"
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<m:GetUsers xmlns:m="Get-Users">
<id>jsmith</id>
</m:GetUsers>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Response
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
<SOAP-ENV:Body>
<m:GetUsersResponse xmlns:m="Get-Users">
<users>
<id>jsmith</id>
<name>John Smith</name>
<dogs>
<dog>
<id>fido</id>
<name>Fido</name>
</dog>
</dogs>
</users>
</m:GetUsersResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
REST vs SOAP
REST Pros
- Aligned with HTTP specification, using it as an application level protocol (as intended)
- Not as strict (depending on how you look at it)
- Lightweight
- Easily called from client-side (i.e. JavaScript)
- Cacheable (GET operations)
- Less verbose
- Human readable
- Easier to build (i.e. frameworks or roll your own) and test (e.g. directly in browser)
- Can return multiple formats
- No need to define a new arbitrary vocabulary (e.g. PUT = insert)
- Widely supported (e.g. Amazon, Twitter, Facebook) — although many are only RESTish (not fully compliant)
REST Cons
- No asynchronous processing or stateful support (reliability, security, transactions)
- Alternative: Tokens (security only)
- No support for exposing business logic
- Only available over HTTP (point-to-point, performance, restricted verbs). SOAP supports SMTP and JMS.
- No formal contract (i.e. strongly typed WSDL) because it is an architecture rather than a protocol
- Alternative: WADL (although not widely supported)
- No default end-to-end security like SOAP WS-Security
- No binary encoding (i.e. attachments)
- Alternative: MIME octet-stream base64 encoding
Conclusion
HTTP OK? AJAX support OK? Stateless OK? Simplicity OK? Go with RESTful or RESTish.
In my commercial experience endpoints rarely change — it’s more likely to be the query parameters (e.g. /books?status=read) or representations they return (e.g. adding a new field). There is also no value having new resources appear in responses as they will still need to be discovered (via documentation), understood (via documentation) and implemented by developers. I’m a fan of making things as simple as possible, which is why I personally prefer RESTful for direct human interaction (e.g. the web) and RESTish for B2B integration (e.g. web services).
Resources
PolyAwesomism 