These are my thoughts and key take aways from Azure API Management Gateway (APIM) from working with it for some years now.

Easy to Expose Services

Whether it’s a new service built on Azure Functions or a Logic App, something existing internally or externally – it’s dead easy to expose services and secure them through APIM. In fact it’s so easy people don’t believe me when I tell them it takes minutes rather than weeks.

The builtin Dashboard and Analytics gives you a complete overview of requests, response times, errors and so on. With Application Insights you get x-ray vision into the complete end to end call stack for all requests.

Branding the (old) Developer Portal

Branding the – now almost defunct old – Developer Portal using the underlying Orchard CMS is simple and quite a lot can be achieved in a day or two. Going fancy is also a possibility if you know someone who can do a bit of HTML magic with JavaScript and CSS.

The only real problem is the underlying structuring of APIs into Products (think of a Product as a subscription for your mobile phone with different plans for talk time, data and so on) that can be a bit of a challenge when trying to present and manage APIs and Products in whatever way a customer thinks is most important for them. I hope the new portal (and an update to the Products feature in APIM with support for nesting) will make this easier.

Takes only a few days to get to above look and feel by someone who is familiar with a CMS and some HTML, CSS and JS.

Updating an API (needs better builtin support…)

Updating APIs with new methods or revisions of existing should be simple as APIM supports OpenAPI V2+3 Specifications (OAS) – so just point APIM to the OAS file and APIM will detect changes and import. However APIM is does not support this. So most of the time you’re down to a complete re-import so then just updating the change by hand is easier.

Yes APIs can be programmatically updated through the APIM Managment API but it’s not straight forward especially in multiple APIM instance scenarios and you’re then forced to write and maintain scripting to handle this.

Microsoft recently released the APIM DevOps Toolkit which aims at making it easier to move APIs between different instances of APIM. This is done using some tools which can alleviate some of the pain but it’s based on quite a bit of low level handling of configuration files in both JSON and YAML, OpenAPI, ARM Templates and some .NET Core utilities – it works but it feels like it’s introducing complexity where it should be solving the underlying problem of seamless support for updating the API methods based on an Open API specification (leave the policies to a second layer of configuration and/or store it in the SCM).

Azure DevOps with API Management Extension

I like the API Management Suite extension to Azure DevOps as it integrates directly in the release pipeline and deploys an API based on an OAS file in v2/v3 and JSON/YAML formats.

The extension also includes several predefined tasks to create/update products and versioned APIs.

I like using a repo to decouple the API team from the development team. So that the API specification can be agreed upon before the actual development takes place. The developers then implements the API according to the specification and maintains any changes to the OAS file.

API Driven Development

There are numerous definitions for API Driven Development (ADD) floating around so I’m just going to share my implementation of it.

Step 1:

  • The API specification is implemented by an “API Architect” in collaboration with the business. This ensures that externally exposed APIs are as homogenous as possible by sharing resource names, paths and data models
  • The specification is pushed to a repo in Azure DevOps

Step 2:

  • The developers implements the API according to the specification
  • The specification is updated with any additional information
  • Automated integration tests are added
  • A PR is created with changes and tests

Step 3:

  • The specification is validated against a common ruleset using Spectral
  • The API specification is deployed to APIM
  • Automatic integration tests are run
API Driven Development with Azure API Management

An API is a Product!

This is perhaps more important that whatever platform and process you use to expose the actual API to your customers.

You have to treat an API as a product – same as any other product you sell. You have to have a team to support it, take care of it, listen to customer feedback and to keep an eye on the SLA.

You can’t expose internal QA versions with limited SLA as the “test” version – everything you expose is IN PRODUCTION – period.

This is in my experience something that requires a bit of getting used to for companies just getting into the API game.