How to Expose Services with Azure API Management

With Azure API Management service you can provide a more cohesive experience for your internal and external partners to access utilize your service portfolio.   Providing developers a single place to explore a menu of available services and operations to integrate with, it provides a host of capabilities to secure, manage and monitor your API’s including support for usage plans, throttling and quotas, payload transformation, alerts, and analytics.

This blog post will go into the steps to creating and configuring an API service to publish to an Azure Service Bus.

Here is what you need before hand:

• An Azure account – Azure free trial
• An Azure Service Bus namespace, with a topic created  – click here for more details on How to use service bus topics

Create an API Management Service

1. Navigate though the Azure management portal and select New in the classic portal and browse to API management service
2. Select Create
3. Enter a name for your new API management service
4. Select the Azure Subscription and Region this new service will reside in
5. Enter the Organization Name, and email address for the administrator for this new service
6. Select Checkmark and continue
7. Once your API Management Service is created
8. Open the publisher portal, and continue

Add An API

• Web API name
  • Public the name of the API as it would appear on the developer and admin portals.
• Web service URL
  • We want to point this to the REST endpoint for your Azure Service Bus created earlier. Sample format: http{s}://{serviceNamespace}.servicebus.windows.net/{queuePath|topicPath}/messages
• Web API URL suffix
  • Last part of the API’s public URL. This URL will be used by API consumers for sending requests to the web service.
• Save your changes

Configure the API

Select API’s from the API Management Navigation

• In the Settings Tab 
  • Add in a description for this API (optional)
  • Save your changes
• In the Security Tab
  • We want to point this to the REST endpoint for your Azure Service Bus created earlier.
  • Sample format: http{s}://{serviceNamespace}.servicebus.windows.net/{queuePath|topicPath}/messages
  • Save your changes
• In the Operations Tab 
  • We want to point this to the REST endpoint for your Azure Service Bus created earlier.
  • Sample format: http{s}://{serviceNamespace}.servicebus.windows.net/{queuePath|topicPath}/messages
  • On the Signature vertical tab
    • In the HTTP Verb field enter “POST”
    • In the URL template field enter “/” (forward slash)
    • In the Display Name field enter a name for this operation, example “Send” or “SendMessage”
    • In the Description enter a description for this Operation (optional) to help your API users
  • On the REQUEST – Body vertical tab
    • Click Add REPRESENTATION button, and enter “application/xml”
    • Enter a sample xml message representation
    • Click Add REPRESENTATION button, and enter “application/json”
    • Enter a sample json message representation
  • On the RESPONSES vertical tab
    • Click ADD button, and enter “202”
    • Enter a description (optional)
    • (Optional) You may click Add REPRESENTATION button and add “application/json” and/or, “application/xml”
    • Enter a sample message representation
  • Save your changes

Configure a Product

Products are the container that users will subscribe to, and to which policies can be applied to in order to handle things like authentication, access restrictions, throttling, and a whole lot more.

To create a product Select Products from the API Management Navigation, and on the New Product form enter the following

• In the Title field
  • Add Name for this new Product, suggestion – “Partner”
• In the Description field 
  • Add a Description for this Product, suggestion – “Partner access to publish messages to Azure Service Bus”
• Require Subscription box 
  • Ensure box is marked, unless you want open access
• Require Subscription Approval box 
  • Mark if you want to use an approval process for subscriptions
• Save your changes

After your New Product is created, select the new product to access its configuration

• In the Summary tab 
  • Click on ADD API TO PRODUCT
  • Mark any API’s you want to include, select the API you added earlier
• In the Description field 
  • Add a Description for this Product, suggestion – “Partner access to publish messages to Azure Service Bus”

Create a Policy for your API

Policies are where we can configure things such as request message transformations, features such as request throttling in order to process both requests and responses to the back-end API’s.

To publish a message to the Azure Service Bus through its REST API we will use a few policy statements to:

• Set the Authorization Header for the Service Bus request
• Convert JSON to XML

More on API Management Policies

To Create/Edit Policies – Select Policies from the API Management Navigation

• Policy Scope page,  by Refining your the scope to set level at which to apply a policy
  • Select your Product from the drop down list to apply policy statements at the Product level
  • Select your API from the drop down list to apply policy statements at the API level
  • Select your Operation to apply policy statements at the Operation level
  • Edit Policy using by editing the XML, if you’ve already save the policy to edit click on “Configure Policy” to re-open
  • Select templates from the left hand side to add them to XML editor, and edit manually
  • More Details – API Policy Reference
  • Save any changes

• Policy Statement to set Authorization Header
  • To set a pre-generated SAS token (using Shared Access Signatures, enter the token in a CDATA tag)

<set-header name=”Authorization” exists-action=”skip”>

<value>><![CDATA[ SharedAccessSignatureToken ]]></value>

<!– for multiple headers with the same name add additional value elements –>
</set-header>

• Policy Statement to set transform JSON to XML
  • To transform JSON formatted messages to XML to forward to service bus

<json-to-xml apply=”content-type-json” consider-accept-header=”false”/>

Test your API operation(s)

You can quickly test your Policies from the API service Developer portal

• Navigate to the Operation you want to test,  and Click on the “Try it” button
  • Select your Product from the drop down list to apply policy statements at the Product level
  • Enter a Test Message in XML or JSON format
  • Select/Confirm your Authorization key is correct for the product subscription
  • Select Send