As described by Microsoft:
"ASP.NET Web API is a framework that makes it easy to build HTTP services that reach a broad range of clients, including browsers and mobile devices. ASP.NET Web API is an ideal platform for building RESTful applications on the .NET Framework."
"Windows Communication Foundation (WCF) is Microsoft’s unified programming model for building service-oriented applications. It enables developers to build secure, reliable, transacted solutions that integrate across platforms and interoperate with existing investments."
Although these descriptions are brief, side-by-side it is easy enough to determine how Microsoft tries to distinguish the two frameworks: Web API is for RESTful services and WCF is for "existing investments." Let's dive into the details about why Microsoft has two service frameworks and when each should be used...
The Basics: SOAP and REST (and OData)
SOAP
Without getting too deep into its history, Simple Object Access Protocol (SOAP) is a Microsoft invented protocol that was meant to create a structured way of sending and receiving data over the wire. This protocol is one of the main foundations of WCF and utilizes XML to create services with typed data and methods. In the typical scenario, a Web Services Description Language (WSDL) file is created from service code and is provided, usually through a static URL, to the client. The client uses this WSDL file to understand what methods are available on the service, how to call them, and what the classes of the returned objects will be. This is a very action-driven model that focuses on what actions a service is a capable of performing.
Example Service Endpoint: http://www.yourcompany.com/SOAPService.Svc
REST
REpresentational State Transfer (REST) is not a protocol, but an architecture and design pattern for building and calling web services. This is the pattern that Web API was designed to utilize to build web services. It is a very resource-drivenarchitecture that exposes endpoints based on objects and not functions. RESTful services also make use of the standard HTTP methods and constructs to exchange data; using GET, POST, PUT, DELETE, and sometimes PATCH a caller can denote which action to perform on the object being accessed at the requested endpoint. Query parameters and content in the body of the request can also provide ways to pass parameters to the service.
OData
Open Data Protocol (OData) is another Microsoft defined protocol (now an open web standard). This protocol extends AtomPub and is a resource-driven model. It allows querying resources on the web service using different endpoints to denote the resource type and query parameters to specify how to filter the results. OData services can also be built using Web API and are usually considered a type of REST service.
Example Query: http://www.yourcompany.com/api/OData.svc/Resources()?$filter=ResourceType eq Images&$top=20
The Decision: Web API or WCF?
Client Interoperability
RESTful services, and therefore Web API by extension, are focused on simplicity and being lightweight. Any application that is able to access a website can access a RESTful service by using the same HTTP calls. This differs from SOAP where the client must understand the web service by utilizing the WSDL file. The WSDL configuration adds some complication and requires additional logic that might not be readily available on many devices (phones, smart TVs, etc.) and programming languages and frameworks.
Coding Overhead
On the client side it is simple to call a RESTful service using HTTP, but hardcoding resource endpoints, serializing and deserializing objects, and recreating custom classes that are returned can be difficult; all of that low level interaction with the web service is abstracted in SOAP services and is "magically" done for you. On the service side, WCF tends to be more configuration heavy and typically requires extensive XML work to get it configured just right. Web API, conversely, has a more standard "out-of-the-box" setup that works for most services, and provides the capability to provide customizable services that extend the base services, such as media type formatters that handle serialization, when needed.
Speed/Bandwidth
Since RESTful services only use basic HTTP, the request and response packets are generally smaller than SOAP request and response packets which package parameters, objects, metadata, etc. in a thick, usually XML, payload. Sometimes this is an important consideration when dealing with mobile or low bandwidth devices. The simple HTTP request/responses also tend to be more human readable than SOAP requests/responses*, although that is not as significant since these services are usually consumed programmatically.
*The caveat to this statement is that WCF services can be customized to use a simpler format, although this isn't the standard implementation. WCF can also utilize HTTP and other protocols, although, again, that is not the standard implementation.
Functionality/Purpose
As described above, SOAP services should be very action-driven and REST/OData services should be very resource-driven. Although any action-driven service can be converted into a resource-driven service, there are some cases where one SOAP call could translate into multiple REST calls; this creates additional overhead in calling the service, increases the complexity of the client's code, and can potentially cause data issues in poorly designed systems. Well designed REST services should be able to mitigate this with indirect actions. As an example, a SOAP call that purchases an item for a customer could do the following:
- Create an order
- Reduce the quantity of an item in stock
- Create a new shipping task
- Update the customer's information and order history
That single SOAP call could translate to four different REST calls updating each of those resources, or, in a properly designed system, one create (POST) PurchaseOrder call that then triggers actions to update the other resources as necessary. Ultimately, RESTful services should be simple and atomic, but SOAP services, for better or for worse, have the flexibility to be bulky and complex.
REST services are more "discoverable" than SOAP services since they can be freely accessed in URLs. Good REST services are also intuitive enough to figure out, both in regard to endpoints and idempotency. As an example, ifwww.yourcompany.com/api/Employees/1 provides the employee with an ID of 1, then it is easy enough to determine that www.yourcompany.com/api/Employee/2 provides the employee with an ID of 2. Assuming you know the service also contains customers, it is again easy enough to determine thatwww.yourcompany.com/api/Customer/1 provides the customer with and ID of 1. Similarly intuitive, using the HTTP actions can reflect the idempotency of a call in REST services. A PUT operation, for example, should be idempotent since you are updating fields with specific values. A similar call in a SOAP service may not be as easy to determine whether it is idempotent or not.
Security
WCF and Web API both have security standards that are accepted. In WCF, highly typed security frameworks and helpers are available to provide enterprise-level security, including security that meets the Web Services Interoperability Organization (WS-I) standards. In Web API, typical web standards are used for security such as Basic and Token authentication, as well as more complex web standards such as OAuth. If properly implemented, security in either framework will be just as good as the other, although some companys prefer and often require specific security implementations. RESTful services, however, do provide a little more flexibility than SOAP that can be useful when authenticating with an external service such as Windows Live IDs, Google, Facebook, or Twitter.
Conclusion
Unfortunately, I cannot say that one is better than the other. Fortunately, there is a fairly straightforward way of determining which framework to use when building a new web service. Go through the paragraphs above and determine who is using the service, how they are using it, and how the service will be built and scaled. My general rule of thumb is: If it's an internal/intranet web service, use WCF; if it's an external/internet web service, use Web API.
No comments:
Post a Comment