Operation-based SOAP vs. Resource-based REST

Applies to: Windows Communication Foundation

Published: June 2011

Author: Robert Dizon

This topic contains the following sections.

• Process Analysis
• Verb-to-Noun
• URI Templates
• Uniform Interface
• Resource Representation

REST was first described by Roy Fielding in his doctoral dissertation, Architectural Styles and the Design of Network-based Software Architectures. If you are interested in reading it, go to http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm.

In general, the practice of generalizing and standardizing the interface between components allows for simplified and observable interactions among the different systems. The web environment uses a standard communication protocol named the hypertext transfer protocol (HTTP). HTTP is a request-response protocol that uses a client-server model. Think of the browser as the client, and a remote application that runs a web site as the server. Typically, a user has a browser open and clicks a link on a web page, or enters a web site address, formatted as a uniform resource indicator (URI), which is a string that identifies a resource on the Internet. The client translates this action into an HTTP request, which uses one of the following methods.

• GET - The GET method requests a specific resource from the server. It occurs whenever a user clicks on a resource that is on a web page. An example of the GET method is GET /images/logo.jpg, which requests that the server return the logo image file to the client.

• PUT - The PUT method creates or updates a resource on the remote server after the client is authenticated first as a separate process.

• DELETE - The DELETE method requests that a resource on the server be either deleted or erased after the client is authenticated first as a separate process.

• POST - The POST method submits data to be processed by the remote server. This method is often used to transmit credentials that users enter on a logon page.

• HEAD - The HEAD method requests a resource's header information.

The server response, or resource, can be an HTML page, or other data that is returned by the server.

The WCF SOAP service can be categorized as operations-based, which means that a SOAP client calls a method that is available as a web service operation on a remote server, and receives a SOAP response. A WCF REST service can be categorized as resource-based, which means that a REST client sends an HTTP request to programmatically accomplish a business objective. These requests largely employ a GET that is sent to a URI. In return, the client receives the corresponding resource.

There are REST guidelines that can help you to design and develop your services. The remainder of this section gives an overview, and shows how they can be applied to a common business scenario. . (For a complete description of these guidelines, see "A Guide to Designing and Building RESTful Web Services with WCF 3.5" on MSDN at https://msdn.microsoft.com/en-us/library/dd203052.aspx). The example is a large construction company that has several cross-cutting business objectives.

The following figure illustrates the steps to follow in order to develop your solution.

Process Analysis

During the process analysis phase, developers worked with the company's management and with its customers to identify and specify the necessary business objectives. The following example shows the steps that lead to a successful bid on a project. The relevant persons and company departments are shown in parentheses.

1. The customer requests a quote (the customer, and Company Sales).

2. The company creates a quote in the enterprise resource planning (ERP) system (Company Engineering, Project Controls, and Sales).

3. The company submits the quote to the customer (Company Sales, and Project Controls).

4. The customer approves the quote (the customer, and Finance).

5. The company begins construction (Project Controls, Engineering, and Finance).

6. The company completes the project, and invoices the customer (Project Controls and Finance).

Verb-to-Noun

The verb-to-noun step identifies one or more similar service processes (these are the verbs) and maps them to the appropriate resources (these are the nouns). The abbreviations in bold are there to help you remember the actual mappings. For example, Q2O is an abbreviation for Quote to Order.

1. Q2O - Quote to Order

   1. The customer requests a quote (the customer, and Company Sales).

   2. The company creates a quote in the ERP system (Company Engineering, Project Controls, and Sales).

   3. The company or customer requests the status of the quote

2. O2P - Order to Project

   1. The company submits the quote to the customer (Company Sales, and Project Controls).

   2. The customer approves the quote (the customer, and Finance).

3. P2I - Project to Invoice

   1. The company begins construction (Project Controls, Engineering, and Finance).

   2. The company completes the project, and invoices the customer (Project Controls, and Finance).

   3. The company or customer requests the status of the invoice

URI Templates

After you identify the fundamental services, create the URI definitions. Here are the URIs for this example.

• customer/ {customer} - The URI template for the customer name.

• user/ {username} - The URI template for the user name.

• Q2O/requestquote - The URI template a customer uses to request a quote.

• Q2O/requestquote/status - The URI template to learn the quote's status.

• Q2O/createquote - The URI template to create a quote in the ERP system.

• O2P/submitquote - The URI template to submit a quote to the customer.

• O2P/approvequote - The URI template to approve the quote.

• P2I/executeproject - The URI template to begin construction.

• P2I/executeproject/status - The URI template to learn the project's status.

• P2I/invoice - The URI template to invoice the customer.

• P2I/invoice/status - The URI template to learn the invoice's status.

Uniform Interface

The uniform interface step associates HTTP methods with the URI templates. The following table lists these associations.

Table 1. Uniform Interface Alignment

Resource Representation

Resource representation defines the data formats, such as plain text, form-encoding, HTML, XML, or JSON. It includes representations for different media, such as images and videos. Currently, the Extensible Markup Language (XML) is the easiest and most popular cross-platform messaging format in use. The following XML code represents the different URIs that are listed in the previous table.

The customer resource uses the customer ID and name to identify the customer. The resource uses the PUT method.

<customer> 
   <Id>cs023982</Id> 
   <Name>Contoso, Ltd.</Name> 
</customer>

The user resource uses the user name and password to authenticate the user. The resource uses the PUT method. It is recommended that you use SSL to create a secure connection when you send this type of information.

<user> 
   <Email>janedow@contoso.com</Email> 
   <Name>Jane Dow</Name> 
   <Password>p@ssw0rd</Password>
</user>

The requestquote resource initiates a request from the customer for a quote. The resource uses the PUT method.

<Q2O>
   <Id>cs023982</Id> 
</Q2O>

The requestquote/status resource returns the status of a quote. For automation, this status can be used to initiate a workflow process such as the creation of a new project. The resource uses the GET method.

<Q2O>
     <Id>cs023982</Id> 
     <Contractor>V9834-2319873</Contractor> 
     <Status>Created</Status> 
</Q2O>

The createquote resource is used internally to create a quote in the ERP system. The resource uses the PUT method.

<Q2O>
     <Id>cs023982</Id> 
     <Status>Created</Status> 
     <Contractor>V9834-2319873</Contractor> 
     <ProjectNumber>CST-093812</ProjectNumber>
     <Location>Site #452 Atlanta</Location>
     <LocNumber>094891-23222</LocNumber>
</Q2O>

The submitquote resource sends a quote and a project number back to the customer. The resource uses the PUT method.

<02P>
     <Id>cs023982</Id> 
     <Status>Created</Status> 
     <Contractor>V9834-2319873</Contractor> 
     <ProjectNumber>CST-093812</ProjectNumber>
     <Location>Site #452 Atlanta</Location>
     <LocNumber>094891-23222</LocNumber>
     <Estimate>45000</Estime>
</02P>

The approvequote resource notifies the company that the customer has approved the quote. This triggers the executeproject resource. The resource uses the HTTP PUT method.

<02P>
     <Id>cs023982</Id> 
     <Status>Approve</Status> 
     <Contractor>V9834-2319873</Contractor> 
     <ProjectNumber>CST-093812</ProjectNumber>
     <Location>Site #452 Atlanta</Location>
     <LocNumber>094891-23222</LocNumber>
</02P>

The executeproject resource informs the customer that the construction project has started. The resource uses the PUT method.

<P2I>
     <Customer>cs023982</Customer> 
     <Contractor>V9834-2319873</Contractor> 
     <ProjectNumber>CST-093812</ProjectNumber>
     <Location>Site #452 Atlanta</Location>
     <LocNumber>094891-23222</LocNumber>
     <Invoiced>Phase-1</Invoiced>
     <FileName>ProjectControlDoc-CST-093812.docx</FileName>
     <CustomerPoDate>01-25-2009</CustomerPoDate>
     <InvoicedDate>03-21-2009</InvoicedDate>
</P2I>

The executeproject/status resource sends a project status message to the customer. The resource uses the GET method.

<P2I>
     <ProjectNumber>CST-093812</ProjectNumber>
     <Status>0043</Status>
     <Description>Tract 1 is completed, Tract 2 is under zoning</Description>
     <Phase>1</Phase>
</P2I>

The invoice resource sends the customer an invoice. The resource uses the PUT method.

<P2I>
     <ProjectNumber>CST-093812</ProjectNumber>
     <Location>Site #452 Atlanta</Location>
     <LocNumber>094891-23222</LocNumber>
     <QuoteTotal>75300<QuoteTotal>
     <OrderTotal>84000<OrderTotal>
     <Invoice_Number>093812-32891<Invoice_Number>  
     <Invoice_Amount>94302<Invoice_Amount>
     <Total_Expenditure>3422<Total_Expenditure>
</P2I>

The invoice/status resource informs the company of the invoice's status. The resource uses the GET method.

<P2I>
     <ProjectNumber>CST-093812</ProjectNumber>
     <Invoice_Number>093812-32891<Invoice_Number>  
     <Status>001</Status>
     <Description>Approved</Description>
</P2I>

The WCF REST starter kit, which is on CodePlex, can help you to build WCF REST services. Download the starter kit and study its samples, as well as the developer's guide, which is on MSDN. The Microsoft.Http assembly that is contained in the kit simplifies the use of the HTTP GET, POST, PUT, and DELETE methods. The assembly also includes a variety of content-specific APIs to help you process responses. The starter kit which is currently superseded by the WCF Web API at CodePlex site (see both links below) also includes a set of Microsoft Visual Studio project templates for common REST scenarios.

The following links provide more information:

• A Developer's Guide to the WCF REST Starter Kit on MSDN at https://msdn.microsoft.com/en-us/library/ee391967.aspx

• WCF Web API - Download Preview 4 on CodePlex at http://wcf.codeplex.com/

• WCF Web APIs at https://channel9.msdn.com/Events/MIX/MIX11/FRM14

Previous article: Wide Support for Protocols

Continue on to the next article: Security Considerations and Conclusion