A Guide to Getting Started with Azure API Management

When you first open Azure API Management (APIM), it can feel a bit overwhelming. There are dashboards, menus, and settings everywhere — almost like stepping into the control room of a complex system, with dials and switches you might not recognise at first glance. But once you know which buttons to press, it becomes much less intimidating. 

This post provides a step-by-step walkthrough of the basics of Azure API Management. By the end, a working API will be in place, along with a clear understanding of how APIM is structured and why it’s useful. 

This guide is aimed at: 

• Graduates and intermediate developers – a practical introduction to APIs in Azure, showing how APIM can build confidence, simplify testing, and make publishing and securing APIs easier. 

• Testers – insight into how APIs are exposed and secured, with hands-on testing both inside and outside Azure. 

• Entry-level architects – if APIM is new to you, this guide shows where it fits in the integration landscape and why it’s a key part of enterprise solutions. 

No matter your role, if you’re new to Azure Integration Services and looking to understand when and why to use APIM, this walkthrough will give you both the confidence and the foundation to build more advanced solutions. 

What is Azure API Management (and why do businesses need it)?

Azure API Management (APIM) is the secure entry point for your APIs. It acts as a controlling layer between backend systems and anyone consuming those services, ensuring access is safe, consistent, and reliable. 

For organisations, APIM provides: 

• Security and compliance – Enforce authentication, subscription keys, and access controls to protect sensitive systems and meet regulatory requirements. 

• Centralised governance – Brings all APIs under one platform, making it easier to apply consistent policies, monitor usage, and reduce operational overhead. 

• Scalability and flexibility – Handles demand spikes, applies rate limits, throttling, and enables caching so backend services remain stable as usage grows. 

• Faster adoption and collaboration – Through its Developer Portal, teams, partners, and customers can discover and test APIs with clear documentation, reducing support overhead and speeding up integration. 

Even a simple example, like a “Hello World” API, shows how APIM provides the same foundation enterprises rely on to secure, scale, and manage their digital services with confidence. 

Before getting started, here’s what you’ll need 

Before we dive in, here’s what you should have ready: 

• An Azure subscription (free trial works fine) 

• Access to the Azure Portal 

• Basic understanding of HTTP requests like GET 

• (Optional) Postman or a web browser for testing outside Azure. 

If you don’t know what a GET request is, don’t worry, it’s just a way to ask a server for some data. You’ll see it in action very soon. 

Step 1 – Create an APIM instance 

Creating an APIM instance is your first step. Think of it as the container that will hold all your APIs. 

1. In the Azure Portal search bar, type API Management services. 

2. Click + Create. 

3. Fill in the basics: 

• • Subscription & resource group – pick your existing ones or create a new group. 
  • Region – Select a region closest to you in this instance I am using NZ North. 
  • Resource Name – Name must be globally unique, best practice is to follow naming conventions but for this example use something like initials and HelloWorldAPIM. 
  • Organisation Name – Enter either your employer’s name or your own. This is used for the Developer Portal. 
  • Administrator Email – Enter your own email to receive all system notifications sent from API Management. 
  • Pricing tier – select Developer. It’s the lowest cost option and perfect for learning. 

4. Hit Review + Create, then Create. 

5. Wait 10–30 minutes for deployment. Azure will set up all the necessary resources in the background. 

Figure 1 – Create API Management Service – Basic Settings

Step 2 – Add a new API

Once your APIM instance is ready, let’s add a simple API. You don’t need a backend service yet — we’ll use a public test endpoint.

1. Inside your APIM instance, go to APIs.
2. Click + Add API → HTTP.
3. Fill in the fields:
   • Display name: Hello World API
   • Web service URL: https://httpbin.org (returns JSON instantly)
4. Click Create.

Figure 2 – Create an HTTP API Basic

Why httpbin.org? It’s a free service that returns JSON instantly. This lets you focus on APIM features without building a backend.

Step 3 – Create a GET operation

APIs are made of operations — basically endpoints that perform actions. Let’s create a simple GET operation.

1. Inside your new API, click + Add operation.
2. Fill in:
   • Display name: Say Hello
   • URL: /get
   • Method: GET
3. Click Save.

Figure 3 – Create a GET Operation

Step 4 – Test your API in Azure

Azure provides a built-in test console, so you don’t even need Postman yet.

1. 1. Go to the Test tab.
   2. Select the /hello operation and click Send.
   3. You should see a 200 OK response with JSON from httpbin.org.

Figure 4 – Testing API Settings

Figure 5 – Testing API – Response Message

Step 5 – Call it from outside

Now let’s see it work outside Azure. This is where APIM’s gateway shines.

1. Go to Settings > Gateway URL and copy it.
2. In a browser or Postman, make a GET request.
3. If subscription keys are required:
   • Go to Subscriptions → copy the Primary key for “Built-in all-access.”
   • Add it to your request headers.

Figure 6 – Responses generated when sending GET request from Postman

Tip: Subscription keys help you control who can access your API. In production, you rarely leave APIs open to everyone.

Step 6 – Adding simple Policies

One of the coolest APIM features is — rules that let you change request or response behaviour. Let’s add a custom header.

1. In the /hello operation, go to Frontend → Inbound processing.
2. Add a Set HTTP header policy:
   • Name: X-Hello
   • Value: Hello World!

<set-header name="X-Hello" exists-action="override">

      <value>Hello World!</value>

</set-header>

Figure 7 – Adding Header to HTTP Response

 

3. Save and test again — the response will now include your custom header.

Figure 8 – HTTP Response with Added Header

 

The Ocp-Apim-Subscription-Key header is automatically added to requests for authentication. Because the header name reveals that APIM is being used and that a subscription key is involved, organisations often rename or remove it before requests reach backend systems. This reduces the amount of platform information exposed externally and keeps sensitive authentication details restricted to the gateway.

4. Once again in the /hello operation, go to Frontend → Inbound processing.

5. Add a Set HTTP header policy:

• • Name: Ocp-Apim-Subscription-Key
  • Exists-action: delete

<set-header name="Ocp-Apim-Subscription-Key" exists-action="delete" />

Figure 9 – Remove Header from HTTP Response

 

6. Save and test again — your backend will no longer receive the subscription key in the request headers.

Figure 10 – HTTP Response with Removed Header Value

Tip: Policies let you do things like rate limiting, authentication, validating, or even transforming data without touching the backend.

Common Beginner Mistakes & Troubleshooting Tips

Even though APIM is beginner-friendly, there are a few pitfalls that many newcomers hit:

1. Typos in URLs or API suffixes – Always double-check paths to avoid 404 errors.
2. Forgetting subscription keys – A missing key results in a 401 Unauthorized error. For initial testing, the Primary key from Built-in all-access works fine, but in production environments, separate Product subscriptions are typically used to manage access.
3. Not testing both internally and externally – Test using the Azure Test tab and then Postman or a browser.
4. Misconfigured policies – Start simple; test each policy individually.

Mini tip: Troubleshooting in APIM gets easier with experience. Every mistake teaches you something about API flow and policies.

What I Learned Doing This

• APIM looks intimidating at first, but the basics are approachable.
• Start small with a simple API and gradually explore more advanced features.
• Policies are the real magic — they let you change behaviour dynamically without touching backend code.
• Even small experiments provide insight into enterprise API management.

Next Steps

You’ve just created and tested your first API in Azure API Management. That’s a big milestone! From here, you can start exploring more advanced features and deployment options, such as:

• Products & Subscription Management – Bundle APIs into logical access groups. This lets you issue subscription keys per Product (e.g., Free vs Premium) instead of using the built-in all-access keys used during early testing.
• Security Policies – Apply authentication and authorisation such as OAuth or JWT validation. These ensure your APIs are only accessed by approved clients.
• Versioning & Revisions – Introduce updates safely. Revisions allow testing changes behind the scenes, while versions keep major updates available side-by-side.
• Monitoring & Insights – Track performance, failures, and usage trends with Azure Monitor and APIM Analytics. This makes troubleshooting and optimisation much easier.
• Developer Portal – Customise how developers discover and test your APIs — complete with documentation, sample requests, and self-service key management.
• Deployment Automation (DevOps) – Manage APIM configuration as code using CI/CD pipelines (e.g., GitHub Actions or Azure DevOps) so deployments are consistent across dev, test, and production environments.

Pro tip: The more you experiment, the faster APIM becomes intuitive. Play, break, and fix — that’s the best way to learn.

Azure API Management v2 Tiers

The v2 service tiers (Basic v2, Standard v2, and Premium v2) represent a newer APIM architecture, designed to support workloads with improved scalability, deployment flexibility, and network integration.

Key Features of v2 Tiers

• Improved Deployment and Scaling
  v2 tiers allow faster setup and easier configuration changes and support more scale units compared to classic tiers.
• Enhanced Networking Support
  Standard v2 and Premium v2 provide better integration with virtual networks. Standard v2 supports outbound VNet integration, while Premium v2 supports full VNet injection for connecting to private backend resources.
• Classic Tiers Remain Available
  The original Developer, Basic, Standard, and Premium tiers (v1 or “classic”) continue to exist. v2 tiers are additional options rather than replacements.
• No Developer v2 Equivalent
  There is currently no Developer v2 tier. The classic Developer tier remains the most cost-effective option for non-production or testing environments.
• Migration Considerations
  Existing v1 instances cannot be upgraded in place to v2, a new instance must be created if moving to v2.

How v2 Tiers Fit into Learning APIM

This guide uses the classic APIM tiers, including the Developer tier, to demonstrate key features in a cost-effective, non-production environment. The v2 tiers introduce improved performance, advanced scaling, and enhanced virtual network integration. While the examples here focus on v1, learning about v2 is valuable, as it represents the direction of the platform and ensures familiarity with features that may replace or supplement v1 in the future.

Final Thoughts

At first, APIM can look like a maze of options, but once you start small and build step by step, the layout becomes more intuitive. By creating a simple Hello World API, adding operations, testing them, and applying basic policies, you’ve taken your first steps toward mastering a powerful tool that helps manage, secure, and scale APIs with confidence.