Five best practices when working with Azure API Management

With the rise of API-driven architectures, Azure API Management (APIM) has become a first-class citizen in most Azure solutions. Here are five best practices that you can apply to whatever use case you are dealing with:

Versioning & revisioning

APIM comes with revisions and versions. Other than the initial version, new versions should be used in the following cases:

• Breaking changes: when you remove or alter an operation to the extent that it is not backward compatible with the previous version. In this case, you MUST create a new version.
• Ongoing deprecation of the current version: even when you do not make breaking changes, know you are about to deprecate the current version shortly. Then you might already create a new non-breaking change version to incite users to use it. It will allow you to announce the deprecation of the current version more quickly.
• Significant feature addition and marketing-related decision: you may want to promote a new version because you want to market/monetize it differently.

Consider using revisions to test a bug fix or a non-breaking change. You can then promote the new revision to the current version to make changes current.

Making use of named values & key vault-based secrets

Named values are variables you can define as part of your APIM instance. They can be reused within policies across APIs, using this syntax: {{NamedValue}}. When storing secrets, consider using key vault-backed named values.

Making use of policy fragments

Policy fragments are code snippets that you can reuse across policies. They allow the building to build more maintainable policy codes. It would help if you used them whenever you have recurrent actions, such as adding response headers or removing request headers from the initial request.

Enabling managed identities

It is considered best practice to enable APIM’s system identity and attach one or more user-assigned identities to the instance. Using a managed identity, you will therefore be able to:

• Extract secrets and certificates from Azure Key Vault
• Authenticate against custom backends that integrate with Azure Active Directory
• Interact with any Azure service that supports Azure Active Directory authentication & authorization

Adopting a KISS approach for your policies

Make sure to adopt a keep-it-simple and stupid approach when crafting policies. Policies are potent but are not comparable to an actual programming language, which can be unit-tested, etc. So, it would help if you tried to keep policies as simple as possible and avoid defining any business logic inside. Policies should be used to:

• Enforce some security controls
• Prevent abuse
• Perform dynamic routing to backends
• Potentially aggregate requests, but not too many
• Apply transformations to the initial request and the response

Any other complex logic, including technical ones, should be offloaded to a utility backend service and called by the gateway when needed.