In previous post I described a way to consume a public Rest API using the BizTalk WCF-WebHttp adapter in combination with JSON-decoder, which is a new component with the BizTalk Server 2013 R2 edition. Now I like to mix things up a bit and consume a different API that is public. That is you can use this API from Last.fm. This is an online music discovery service that gives you personalised recommendations based on the music you listen to. To use the API of this service you need to registering yourself first. Because when you call of one of the methods of the API you need to stick in an api_key as one of the parameters of your request. This is not uncommon as various cloud API’s have this kind of mechanism.
Scenario
I have the following scenario, where I have built a client application (still one of those old fashioned guys that use window forms). The client application have the following functionality:
- Get information of an artist.
- Get the top albums from the artist.
Information and top albums can be obtained through calling the Last.fm API artist methods. The client will via BizTalk call these API methods. Similar as in my previous post calling the Airport Service to retrieve its status. Below you find an overview of the scenario.
The communication with the internal endpoint in this scenario will be SOAP/XML. The endpoint is hosted in a two way receive port (request/response). It exposes schemas for two operations: GetArtistInfo and GetTopAlbums. The request message will subsequently be mapped to a REST call to the service indicating that the expected response format is Json or default xml. BizTalk will decode the response into XML, so that it is published as an XML message in the MessageBox in case the response message is Json (GetArtistInfo) otherwise it will be just received by the adapter (GetTopAlbums). The receive port will subscribe on that message so it will be routed back as response to the client that on his turn renders it in the UI (Form). This scenario shows that BizTalk acts as a broker and protocol mediator (SOAP/XML –> REST/JSON –> SOAP/XML or SOAP/XML –> REST/XML –> SOAP/XML) between internal client and the external Last.fm API.
The solution of the described scenario consists of the following parts that will be discussed in the subsequent paragraphs:
- Exposing schema’s for internal service exposing an operation to client application that will consume the service.
- Creating a custom receive pipeline to enable decoding of Json message to xml (see previous post).
- Configuration of a Send Port with the Web-Http adapter (or binding if you like), send and receive.
- Demonstrating the solution.
Exposing schema’s as service
To support both calls from the client to the Last.fm API the request schema’s are as follows:
Both request schemas look the same expect for the root name. These could be consolidated to one schema, nevertheless I choose to keep each method call isolated. Both schema contain promoted properties. The elements need to be promoted to variable mapping later when configuring the send port with WCF-WebHttp adapter to support dynamic URL mapping.
The response for the GetArtistInfo will be Json and therefore I will use the postman application in Google Chrome:
Here you can see that for calling the API you need a method parameter, artist name, api_key and format. However, the format is optional. By default XML will be returned when no format has been specified. The Json response can be used as instance for creating an XSD using the JSON Schema Wizard in Visual Studio BizTalk templates. The schema looks like:
Similar approach will be used to get an instance of the response to the GetTopAlbums call. This schema will be based on XML. Having the schemas enabled me to create an internal service that exposes two methods.
Once I have the internal service up and running the next part is to create a custom pipeline for receiving the Json response from the GetArtistInfo API method call. The Json decoder will be specified to serialize that response into XML. For the GetTopAlbums no specific custom pipeline is necessary. The schemas and custom pipeline will be deployed to BizTalk runtime.
Creating and configuring the Send Port with the Web-Http adapter
To be able to communicate with the Last.fm API and call both methods I will need to have two send ports configured with the WCF-WebHttp adapter. The Last.fm API doesn’t require authentication other than supplying the api_key as a parameter in call tp any of the API methods. In the general tab of the WCF-WebHttp Transport properties the address of the service can be specified (URI). Besides the address I need to specify here the HTTP Method (GET) and perform a URL mapping.
The URL mapping will be interesting as I need to add a few parameters to my REST call.
https://ws.audioscrobbler.com/2.0/?method=artist.getinfo&artist=Metallica&api_key=<your last fm api_key>&format=json
My HTTP Method and URL Mapping will look like:
<BtsHttpUrlMapping><Operation Method=”GET” Url=”/?method={method}&artist={artist}&api_key={api_key}&format=json”/></BtsHttpUrlMapping>
Interesting thing in this URL mapping is that & is and &. If you try to just use the & you will run into an error like depicted below:
Next I click Edit… to do the variable mapping i.e. map the parameters to promoted properties of my incoming request message.
Variable is mapped to the property namespace that defines the API_KEY, ARTIST and METHOD.
The general tab is important for specifying the address, method and URL mapping. The other tabs are:
- The Binding tab provides you the 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 Last.fm API 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 suppress!
For further details on configuration settings for these tabs see MSDN article How to Configure a WCF-WebHttp Send Port.
Test the solution
Now building the client to call the Last.fm API methods indirectly via BizTalk was quite some work. I wanted to render the information nicely in a Windows Form. When I enter an artist name and click GetInfo then a request will be send to BizTalk routed to the send port that communicates with Lastfm API and request info of the band Metallica.
The response of the message is nicely rendered in the above form. When I click TopAlbums another request is sent to a different send port that send to a different Last.fm API method.
If we look at the traffic between BizTalk Server and Last.fm using Netmon I can examine what goes over the wire.
This blog has demonstrate how fairly easy it is to consume a Json message with BizTalk Server 2013 R2 after invoking a Rest API. And how I was able to leverage an API from Last.fm. The cool thing is that BizTalk Server 2013 R2 is capable to communicate with tons of REST API’s out there in the cloud with the WCF-WebHttp adapter. And with JSON support things get less complex. I haven’t tried communicating with an API that requires Basic- or OAuth authentication. I probably will have to do some custom coding using behavious like explained in the blog post from Quicklearn.
Cheers,
Steef-Jan
