Working with Azure API Management

Azure API Management is the outcome of the acquisition by Microsoft of Apiphany, and as such it has its own management interfaces. Therefore, it has a slightly different look and feel to the standard Azure Portal content.

The Developer portal and Publisher portal are described in detail in this section, but first a new instance of API Management is required.

Once created (and the provisioning in the Azure infrastructure can take some time), most interactions take place through the Developer portal and Publisher portal.

Creating your first Azure API Management instance

Azure API Management is accessed via the Classic Portal:

The creation of an instance is straightforward and follows three steps via a wizard:

1. Enter the URL, which has to be globally unique and choose the SUBSCRIPTION and the REGION.
   
2. Enter an ORGANIZATION NAME, which appears on the portals, and an ADMINISTRATOR E-MAIL address to which alerts and requests for access are sent. By default, a developer instance is created, to choose either Standard or Premium, click on the ADVANCED SETTINGS checkbox that provides access to the third page in the wizard. At the time of writing, a developer instance is free, but has limited capabilities.
   
3. Finally, choose the pricing tier required from Developer, Standard, or Premium.
   

After completing the wizard, the instance is provisioned. Once complete, the instance scale and pricing tier can be configured within the Classic Portal, along with DNS names and VPN connections.

All other management tasks are handled through the Publisher portal, which is accessed by clicking on the MANAGE link, while the Developer portal is accessed via the BROWSE link.

Publisher portal and Developer portal

There are two portals that allow interaction with an API Management instance, each of which has a different audience.

The Publisher portal is used by administrators to manage the instance and to configure and manage the Developer portal, including writing content such as blog entries that can be viewed by the development community. This is discussed in more detail in a later section.

The Developer portal is used by developers to browse the published APIs, look at documentation, and subscribe to published APIs. It can also be used to try out APIs through an interactive interface and view usage information. It is the main utility for developers and as such can be used to provide not only information about the APIs but also other information that could be of use to the development community.

Importing the API definition through the Publisher portal

It is possible to add an API definition manually, including defining endpoints and operations, but it is much simpler to import your API definition through the Publisher portal:

There are a number of ways to achieve this:

• From clipboard: This allows pasting the API definition into a text box
• From file: This allows browsing for the API definition from a file location
• From URL: This allows the entry of a web URL that contains the API definition

Azure API Management supports API definitions provided either as WADL or Swagger.

Both Swagger 1.2 and 2.0 are supported.

The Web API URL suffix text box is important as this defines how the API appears to the outside world.

Azure API Management does not expose the raw URL of the imported API, but instead provides a URL in the following format:

http(s)://<APIM Instance Name>.azure-api.net/<Web API Suffix>

It is this URL that developers wishing to consume the service use to access the API operations:

Once imported, the API has a number of settings that can be configured, the most important of which is how security is to be applied. Securing your backend APIs is discussed in detail later in the chapter. However, it is important to consider how developer access is controlled and maintained.

Managing user access rights for Products and APIs

User access is provided at the product level, with products being a container for APIs.

As mentioned earlier in the chapter, there are three default groups that define access to and visibility of Products:

• Administrators
• Developers
• Guests

New groups can be added that can be applied to new products to allow the customized tailoring of functionality through policies that are scoped at the product level.

Users can be manually added or invited to products as required using the Publisher portal.

When developers visit the Developer portal, they can log in if they have previously signed up for an API Management account and can then request access if they have not already done so. If they have not signed up, they can do so by filling in a form. The sign up process uses multifactor authentication for additional security. An e-mail is sent (based on one of the e-mail templates within the Publisher portal) that contains a verification link to finalize sign up process:

Once logged in, developers are able to try out APIs and subscribe to products. To subscribe to a product, the developer needs to click on the Subscribe button under the relevant product.

When a developer requests access through the Developer portal, their entry may be controlled through an approval workflow that requires an administrator to explicitly grant access, based on the setup of the product.

Once approved, the developer can access their subscription keys through their profile on the Developer portal.

This approach to security allows fine-grained control over access to products, with the product functionality being further controlled through the use of policies.

Once a developer has been granted access to the APIs managed by Azure API Management, they are able to build applications that consume them. Once built, the portal allows developers to publish and promote their applications for other developers to use.

In order to provide a good experience for developers, the Developer portal is highly customizable, and this is now discussed in more detail in following sections.

Customizing the developer experience

The Developer portal is essentially the shopfront for your organization's APIs and as such can be tailored to meet the specific needs of the target developer community.

Customizing the experience for developers is managed through both the Publisher portal and the Developer portal. The experience is familiar to anyone with the experience of content management systems.

Page layouts can be changed, including full branding of a site using different fonts and images that are accessible via a web URL. It is possible to upload media to the API Management instance for use within the Developer portal.

Pages can be added and removed as necessary, including full customization of how and where products are displayed to the developers.

The content management system contains a rich set of parameters that can be used as placeholders within the page structure and layout. They are replaced when a developer visits the Developer portal, for example, developer name and product lists.

Since the portal is just an HTML site, it is possible to include additional external controls and widgets that allow further customization.

For this example, we will change the title of the landing page, add an image, create a new menu item linking to some pages, and add a discussion and comments board.

Updating the title of the landing page and adding an image to the title bar is performed within the Publisher portal.

In order to add an image, it first needs to be uploaded to the Media Library within the instance.

First, we need to create a folder and then upload the image to that folder. Once uploaded, the link to the image can be copied by right-clicking the filename link that is part of the thumbnail information.

To add the image to the page and amend the title, we need to update one of the widgets on the page. Widgets are added to the areas of the screen that contain content, such as header and footer, and these can be amended as required. For instance, using an HTML widget for page content allows the content of that area to be specified using simple HTML and inline styling.

There are a number of widgets that quickly allow content to be added to a page; for example, Recent Blog Posts or Menus.

Pages within the portal are made up of a set of layers. By default, there are two layers-one for a Regular page that applies to each page within the Developer portal and one that has additional content specifically for the Home page.

Because we want to have the title on each page amended, we need to update the Regular page content; in this case, within the Header widget.

As the Header is an HTML widget, we can simply update the HTML with the link to the image we uploaded and update the title.

Next, we will add a new menu to the site. In this case, the menu will contain a link to two blogs that have been created for the site. Blogs are created within the Publisher portal under the Blog link.

To create a new menu, we need to click on the Navigation side menu link and then the Add a new menu…   link.

We created two blogs-one for APIs and one for Applications (not shown earlier but via the Blog menu item), and in order for these to appear in the menu, we need to add a custom link for each giving both the text and the URL to the blog.

Once complete, we have our new menu that can now be applied to one of the layers within the pages of the Developer portal.

We will add the menu to the Regular page layer so that it appears on every page. Within the Regular page layer, there is a Navigation widget containing the main site navigation. We will add the new menu widget with a position of 2, which means that it will appear after the main menu.

We can now view the results of these customizations by looking at any page within the Developer portal since all changes we made were to the Regular page layer.

While we amend general layout and add content via the Publisher portal, the site can also be amended and controlled more granularly via the Developer portal for any user logged in as an ADMINISTRATOR.

We will add a discussion board provided by the online tool Disqus to the operations page of all APIs. First, we need to sign up for a Disqus account and add a new page for our API Management site. We can then use a Universal Code snippet to add to the operations page.

The Universal Code snippet is some HTML and JavaScript code that posts any comments back to the Disqus platform and displays the discussions and comments within the page.

To add the code to the page, we need to change the operations template within the Developer portal. When we chose the template we wish to change, we see the page, the HTML of the template, and a set of data that can be used within the template as placeholder information.

We need to add the code to the bottom of the template and make some amendments to the downloaded code snippet from Disqus to ensure that the comments are unique to the API:

<p id="disqus_thread"></p>
<script>
/**
 *  RECOMMENDED CONFIGURATION VARIABLES: EDIT AND UNCOMMENT THE 
        SECTION BELOW TO INSERT DYNAMIC VALUES FROM YOUR 
        PLATFORM OR CMS.
 *  LEARN WHY DEFINING THESE VARIABLES IS IMPORTANT: 
        https://disqus.com/admin/universalcode/#configuration-variables  
    */
var disqus_config = function () {
    this.page.url = "";  // Replace PAGE_URL with your page's 
                                canonical URL variable
    this.page.identifier = "{{apiId}}"; // Replace PAGE_IDENTIFIER 
                                             with your page's unique 
                                               identifier variable
};
(function() { // DON'T EDIT BELOW THIS LINE
    var d = document, s = d.createElement('script');
    s.src = '//sunnyelectricalsapi.disqus.com/embed.js';
    s.setAttribute('data-timestamp', +new Date());
    (d.head || d.body).appendChild(s);
})();
</script>
<noscript>Please enable JavaScript to view the <a 
    href="https://disqus.com/?ref_noscript">comments powered by 
    Disqus.</a></noscript>

Once we have completed our updates, we need to save the template and then publish the changes to the site:

Once published, the discussion board can be seen at the bottom of the page and new comments added as normal.

We have shown how easy it is to add and update content within the Developer portal. This is essential to ensure that developers wishing to use your APIs are fully engaged and want to keep coming back.

By adding a discussion board to the API page or adding Blogs that showcase updates to the API catalog, it will be possible to provide closer engagement with the developer community.