Introduction
Azure API Management (APIM) is a fully managed service that enables integration developers and DevOps to streamline our work with a single place to manage all APIs.
APIM helps protect our resources and lets us control how data and services are exposed to consumers by applying authentication, authorisation and usage limits.
All APIs can be easily managed and shared with internal teams or external partners from a customisable developer portal.
Using APIM, we can keep all APIs behind a single domain, configure their policies and scale with response caching to improve latency.
We can now forget about manually adding requests in Postman or deploying code changes for Swagger UI. Let's take a moment to explore the modern API management service today! 🤓
Prerequisites
Since this is a learning-by-doing blog post for beginners, I would recommend you to follow along in order to understand it. The following prerequisites should be accomplished before we start:
- Microsoft Azure account
- Experience with REST APIs, Azure Functions and Azure Portal
Create a resource
- Create a new resource group in the Azure portal
- Search and add a new API management service to the resource group:
- Carefully select a pricing tier depending on your specific requirements for SLA, features and prices:
- The Consumption pricing option is the lightweight and serverless version of API management service, billed per execution only. It does not include the developer portal.
- The Developer pricing option is for non-production use cases and evaluations, billed hourly. It does not include SLA but it includes the developer portal.
- Review and create the resource
- Let's go get some coffee while waiting for the deployment to complete! ☕
Explore the API management service
When the deployment is finished, go to the new resource and go to APIs > APIs to explore the Echo API and its operations. The Echo API is added to your API management service in the Developer pricing tier by default. You can view its operations and modify its policies (Frontend, Inbound, Backend, Outbound) in the Design tab:
You can change the API names, description, web service URL and API URL suffix in the Settings tab. You can also try out this API by making requests to its operations in the Test tab or you can manage revisions in the Revisions tab.
The API management service can also allow you to add your APIs by manually defining a new API or creating it from Azure resources such as Function App:
Explore the developer portal
The API management service offers a developer portal where API consumers can discover your APIs, learn how to use them, request access, and try them out. A developer portal is a fully customisable documentation website of your APIs.
To launch the developer portal from the API management service in the Azure portal, go to Developer portal > Portal overview and click the Developer portal link to open it in a new browser tab:
When you're logged in as an administrator, you can customise the UI of the developer portal:
You need to publish the portal and enable CORS to make your changes and customisations available to visitors:
Manage users
When your visitor visits the developer portal, they can sign up as a new member:
Upon completing the registration, your user can log in and browse the APIs and Products in the developer portal:
Users of the developer portal can be managed in the Developer portal > Users in the API management service. Each user can be a member of one or more user groups:
Manage groups
Go to Developer portal > Groups to manage groups. The API management service has the following built-in groups whose membership is managed by the system.
- Administrators for Microsoft Azure subscription administrators
- Developers for signed-in users
- Guests for unauthenticated users visiting the developer portal
Members are automatically added to built-in groups. You can delete a built-in group but you cannot change members of a built-in group.
You can add custom groups and add or remove members from a custom group:
The next section will show you how to utilise groups to manage the access control of your APIs and products in the developer portal.
Manage products
API providers use Products to group APIs, and define terms of use, and runtime policies. API consumers can subscribe to a product on the developer portal to obtain an API key to call the APIs.
The developer portal adds two products by default: Starter and Unlimited. Go to APIs > Products to add a new product, for example, Basic:
Go to Product > Settings to change the display name, description, state (published or unpublished) and make it require subscription and approval, set a subscription count limit and legal terms:
Go to Product > Access control to specify which groups can access the product in the developer portal:
A member of the Developers group can now see the Basic product on the Products page in the developer portal.
An API consumer can also subscribe to the Basic product:
Since we make the Basic product require approval, all subscriptions must be approved by an administrator. You can view pending approval subscriptions in the Product > Subscription:
Click the three dots to see all commands that can be performed on a subscription and activate the subscription:
Manage subscriptions
After the subscription is approved by the administrator, the API consumer can see their subscription on the Basic product. Because we set the subscription count limit to 1, each user can only have one subscription to the Basic product. It is possible to change the subscription count limit to allow the user to have multiple subscriptions for the same product.
The user can also click the subscription name to view the subscription details on the developer portal. They can rename or cancel the subscription, and show or regenerate the API keys.
Now, if the user tries out the Echo API using the Basic subscription, the Ocp-Apim-Subscription-Key is automatically populated with their subscription key and appended to the request header:
The user receives the 200 OK status in the response:
Finally, the user can use the subscription key to call the APIs from their applications.
An administrator can change the API key header name or query parameter name in APIs > APIs > Settings:
An administrator can go to APIs > Subscriptions to manage the subscriptions across all products and users:
Things to remember:
- A group can add one or many users
- A user can be added to one or many groups
- A product can add one or many APIs, one or many groups and one or many subscriptions
- A user can add one or many subscriptions and one or many products
Summary
In this blog post, we have learnt how API management service can help streamline our work with a single place to manage all APIs and improve the API discoverability with the developer portal.
We have learnt how to create APIs, users, groups, products and subscriptions from the Azure portal and from the developer portal.
There are a lot more that you can do with the API management service. For example, enabling Active Directory logins, configuring policies, mocking API and throttling, caching, logging and adding Application Gateway. I will save them for the future blog posts.