BizTalk Server 2013 - you can now connect to every REST service out there more easily out-of-the-box
In BizTalk Server 2013, it is easier than ever to connect to a REST service. Before we go into the details of how it is done now, lets take a look at how we would have achieved the same using earlier versions of BizTalk Server.
Invoke ReSTful Web Services with BizTalk Server 2010 is a very good wiki explaining the steps involved to invoke a REST service using BizTalk Server 2010. Apart from creating the BizTalk artifacts, it includes creating a message inspector, an endpoint behavior and a behavior extension element. If you are well versed with WCF, this might be a breeze. If you are not and/or you are creating it for the first time, it could be quite intimidating.
You can still do it in BizTalk Server 2013. However, it is a lot simpler now thanks to the new WCF-WebHttp adapter. Think of it as the REST adapter. Apart from creating the BizTalk artifacts, it includes configuring your send port, providing the REST service endpoint and specifying the authentication. The key difference here is that all this is done via configuration in send port, and the implementation details are handled by the WCF-WebHttp adapter.
Lets take a look at what it takes to connect to a REST service using BizTalk Server 2013
Connectivity to Windows Azure Marketplace
Almost all cloud services that are out there today expose their operations via REST. To start with, lets take a look at how we can consume a data feed from Windows Azure Marketplace. Windows Azure Marketplace is an online market for buying and selling finished SaaS applications and premium data.
Some of these datasets are free and one can subscribe to it via Windows Live Id. One such dataset is US Air Carrier Flight Delays. It exposes one operation called On_Time_Performance. The Details tab in the same page lists down the REST API details
REST API : https://api.datamarket.azure.com/oakleaf/US_Air_Carrier_Flight_Delays_Incr/v1/
Operation : On_Time_Performance
The service is authenticated with an account key and customer ID which is associated with the Windows Live Id.
Here are the configuration settings in BizTalk Server to connect to that REST service end point.
Send Port
The send port makes use of the new WCF-WebHttp adapter to invoke the REST API call.
Send Port configuration
General tab
Address (URI) : https://api.datamarket.azure.com/oakleaf/US_Air_Carrier_Flight_Delays_Incr/v1/On_Time_Performance
HTTP Method and URL Mapping : GET
Address is set to the REST API to be invoked. In this case, HTTP Method is GET. If you are using any other HTTP Method such as PUT, POST, DELETE, PATCH, HEAD, etc. it is supported as well.
In this case, we are invoking only one REST API operation and hence we have provided the full URI in the Address box and we haven't specified any URL mapping in HTTP Method and URL Mapping. The specifics of URL mapping is covered later in this blog post
Security tab
Security mode : Transport
Transport client credential type : Basic
Security mode is set to transport since the REST API endpoint makes use of https. Transport credential type is set to basic since the Windows Azure Marketplace dataset is authenticated using username and password.
Username and password is set in the Username credentials settings.
Messages tab
Suppress Body for Verbs : GET
While performing a GET operation, the message body is usually suppressed and it is the case here as well. To ensure that the outgoing GET API call doesn’t contain a message body, the Suppress Body for Verbs is set to GET.
While making a PUT/POST API call, a message body is usually required. Hence if you are making GET, PUT and DELETE operations, and GET/DELETE do not require message body while POST operation does then you need to set Suppress Body for Verbs to GET, DELETE.
To recap, the configurations that were set in the send port were related to the REST API end point, the HTTP method, authentication details and a setting to suppress message body.
With this config driven approach, connectivity to Windows Azure Marketplace dataset is now established.
Connectivity to Windows Azure Storage
Another example of a cloud service that exposes REST API is Windows Azure Storage. You can store files in Windows Azure Blob Storage and as you can expect, one can perform basic operations such as
- List containers in a storage account [GET]
- List files in a container [GET]
- Get the content of a specific file in a container [GET]
- Create a new file [PUT]
- Delete an existing file [DELETE]
The config driven experience is pretty much the same as the one outlined for Connectivity to Windows Azure Marketplace. One key difference in this scenario is that we can now perform more than one operation in the REST endpoint. We can create 5 different endpoints each capable of performing one operation, or we can create one send port which can perform one of the 5 operations.
Here are some interesting settings to take a note of
Send Port Adapter Configuration
General tab
Address (URI) : https://btstecheddemostorage.blob.core.windows.net
HTTP Method and URL Mapping :
<BtsHttpUrlMapping>
<Operation Name="ListContainers" Method="GET" Url="/?comp=list" />
<Operation Name="ListFiles" Method="GET" Url="/{mycontainer}?restype=container&comp=list" />
<Operation Name="GetContent" Method="GET" Url="/{mycontainer}/{myblob}" />
<Operation Name="CreateFile" Method="PUT" Url="/{mycontainer}/{myblob}" />
<Operation Name="DeleteFile" Method="DELETE" Url="/{mycontainer}/{myblob}" />
</BtsHttpUrlMapping>
In the previous example of Connecting to Windows Azure Marketplace, only one operation was involved. Hence, the address was set to the actual REST API end point and HTTP Method and Url Mapping was set to the HTTP method, namely GET.
Here, the intent is to perform more than one operation. Hence, the Address is set to the base address of the REST API. HTTP Method and URL Mapping contains the list of operations that can be invoked. Note that each operations contains its HTTP method and the relative URL of the REST API.
Variable mapping
If you look at the relative URL closely, you will notice that it contains placeholders, {mycontainer} or {myblob} as opposed to actual value. This is a new concept in BizTalk Server 2013 and it is referred to as variable mapping. Lets take a moment to understand what it means.
In most business flows, you want to invoke an operation (REST API call) based on the business context. For example, get the products associated with a particular opportunity. In this case, opportunity ID will be present in the context of the runtime message and not a hardcoded value. Since we are making outbound REST API calls, the intent is to make sure that we enable such API calls based on the business context as well, if required.
Lets take ListFiles operation as an example. Its relative URL is defined as
“ /{mycontainer}?restype=container&comp=list”. Here {mycontainer} is a placeholder and its value is associated at runtime from the message context. This mapping of the placeholder/variable to the property in the message context is known as variable mapping.
The exact mapping can be set in the Variable Mapping Edit section.
Note that the variables/placeholders namely myblob and mycontainer are now mapped to properties BlobName and ContainerName from property namespace https://ConnectToAzureStorage.PropSchemaAzureStorage
The property schema is part of BizTalk artifacts and created outside the scope of this send port configuration.
Understanding the role of BTS.Operation
When a message comes into BizTalk and is routed to the send port, any one of the five operations can be invoked.
However, we need to specify which operation to invoke. This is achieved by setting the BTS.Operation context property in the incoming message. This property is present as part of a system property schema.
Property schema : BTS.bts_system_properties
Target namespace : https://schemas.microsoft.com/BizTalk/2003/system-properties
Property (element name) : Operation
This can be set as part of property promotion in disassembly stage, custom pipeline component, or in orchestration. As long as it is set before it reaches the send port, BizTalk Server will know which operation to invoke.
Behavior tab
Another key difference here is the authentication mode for Windows Azure Storage. Unlike Windows Azure Marketplace, it is not basic authentication. Instead, it has its own authentication mode.
BizTalk Server 2013 supports authentication mode for Windows Azure Storage out-of-the-box. This is achieved through an end point behavior.
In the behavior tab, right click EndPointBehavior and click Add Extension
Notice the azureStorageBehavior. Select it and provide the azure storage connection properties
Note that all the new WCF adapters in BizTalk Server 2013 provides ACS authentication support. So, if your service end point is authenticated via ACS, you can configure the ACS settings in the Security tab.
On the other hand, there are also services which do not make use of ACS and have their own custom authentication. In these cases, it is really simple to create a custom end point behavior and use it in a way similar to the one shown above for Windows Azure Storage.
Conclusion
Hopefully this blog post provided an overview of the possibilities to connect to REST services using BizTalk Server 2013.