BizTalk Server 2013: Consuming a RESTFul Endpoint using WCF-WebHttp

  • Article

Introduction

BizTalk Server 2013 offers few new adapters out-of the box. One of them is the WCF-WebHttp adapter that offers REST Support. Since the IT-landscape has changed significantly over last years with the rise of multiple devices (phone, tablet, and so on), the Cloud and increased usage of protocols like REST. Twitter, Google, Salesforce, eBay, Amazon all offer REST API's to use their services. The WCF-WebHttp adapter in BizTalk gives you the ability to send messages to RESTful services and receive messages  through an exposed endpoint. This article will described how to consume a ReSTful endpoint using WCF-WebHttp.

Note: This article is based upon the following blog post made by the author BizTalk Server 2013: New Adapters Series: WCF-WebHttp.

REST API

A vast majority of the (webservices in the cloud these days are REST based. When exposing a public API over the internet to handle CRUD operations on data REST has now generally been considered the best option. This API or RESTFul web service is a web API that implements HTTP and REST principles. This best described by Wikipedia as follows:

*It is a collection of resources, with four defined aspects:
*

  • the base URI for the web API, such as http://example.com/resources/
  • the Internet media type of the data supported by the web API. This is often JSON but can be any other valid Internet media type provided that it is a valid hypertext standard.
  • the set of operations supported by the web API using HTTP methods (e.g., GET, PUT, POST, or DELETE).
  • the API must be hypertext driven.

Source: Wikipedia Representational state transfer.

The WCF-WebHttp supports REST thus the operations GET, PUT, POST and DELETE when communicating with a RESTFul web service.

Consume a RESTFul endpoint

There are many web services available now in the cloud that can be consumed using the WCF-WebHttp adapter. To demonstrate how to consume a relatively simple RESTFul Endpoint I choose one of the RESTFul Service endpoints of the US Federal Aviation Administration: The Airport Service. This Service provide the airport status and delay information from the Air Traffic Control System Command Center (ATCSCC) for every US Airport. It has one endpoint that only supports GET operation.

The GET request is the fundamental, widely used operation in the REST world. You can simply visit a URL in a browser (or programmatically) and for instance in the case of the Airport Service type the following URL:

http://services.faa.gov/airport/status/SEA?format=xml

The browser will return a machine understandable structured data like below:


Figure 1. Response message from Airport Service Rest Endpoint.

Scenario

The following scenario describes how the airport service is consumed through BizTalk:

From a client application a request for the status of an airport will be send. BizTalk will map this request to a GET operation to the Restful service endpoint. The endpoint will provide the status of a given airport based upon the airport code provided within the request URL. The result will be routed back to the client application, where it will be rendered in a Windows Form.

Figure 2. Scenario Consume RestFul Endpoint of the Airport Service

Configure the Send-Port using the WCF-WebHttp

To be able to consume the Airport Service with BizTalk you will need to have a send port configured with the WCF-WebHttp adapter. This can be done by configuring the WCF-WebHttp adapter or binding if you like in case you choose WCF-Custom. The configuration is pretty straight forward. The Airport Service is a public service that requires no authentication for its usage. In the general tab of the WCF-WebHttp Transport properties the address of the service can be specified (URI). Besides the address you specify here the HTTP Method (GET) and perform a URL mapping.

Figure 3. WCF-WebHttp Transport Properties General Tab.

HTTP Method and URL Mapping

In HTTP Method and URL Mapping section you specify the method (operations) you are going to perform. In the case of the Airport Service this is going to be only the GET. In case you use an orchestration that the Name has to be specified, which is the name of the operation of the logical port. The URL mapping you define what is going to added after the specified URI. To make it more dynamic instead of hard-coding in general or like in this scenario the airport code you make use of variable mapping configuration feature. So what's between the brackets is a variable that can be mapped to promoted property. The HTTP Method and URL Mapping looks in this case like:


<BtsHttpUrlMapping>
    <Operation Method="GET" Url=”status/{airportcode}?”/format=xml"> 
</BtsHttpUrlMapping>

Variable Mapping

Variable mapping is powerful technique to define any custom variable (or place holder) in your Url, in this scenario case {airportcode} and map that variable to any context property with property name and namespace. The Variable mapping is specified by click the Edit… button.

Figure 4. Variable Mapping with WCF-WebHttp Transport Properties General Tab.

Variable is mapped to the property namespace that defines the airportcode.

WCF-WebHttp Transport Properties

The general tab is important for specifying the address, method and url mapping. The other tabs are:

  • The Binding tab provides you ability to configure the time-out and encoding-related properties.
  • The Security tab provide you the ability to define the security capabilities of the WCF-WebHttp send port.
  • The Behaviour tab provides you the ability to configure the endpoint behavior for the send port.
  • The Proxy tab provides you the ability to configure the proxy setting for the WCF-WebHttp send port.
  • The Messages tab provides you the ability to specify how the message is sent to the REST interface.

Note: In this scenario we only use GET operation of the Airport service. Based on the verb you have to specify in the Suppress Body for Verbs the GET, because a payload is not required for this operation. Since BizTalk sends out messages with a payload this needs to suppressed!

Figure 5. WCF-WebHttp Transport Properties Messages Tab specifying GET verb in Suppress Body for Verbs property.

For further details on configuration settings for these tabs see MSDN article How to Configure a WCF-WebHttp Send Port.

Wrap up

This article described a basic scenario of consuming a public REST service. As you can see the configuration of the WCF-WebHttp is fairly easy. It will get more complex, when security comes into play when access a REST service. The support for REST in BizTalk Server 2013 is major improvement given the fact of vast number of REST services available in the cloud today.

Call for action

In case you want to try or find out yourself how to work with the WCF-WebHttp Adapter you can find a sample for this scenario on code gallery: 

Besides this sample there are a few others available online:

See Also

Read suggested related topics:

Another important place to find an extensive amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.