In this video, I'm going to share how you can become an Azure API Management Pro. You'll learn everything from creation and management to adding artificial intelligence, to adding any type of policy, and so much more. Our 20-chapter Master Class follows the Microsoft Hands-On Lab for APIM. This is created and managed by the very team who built the Azure API Management Service. I'm a Microsoft Azure MVP, here to guide you on your journey.

Now, if you're ready to become an expert in Azure API Management, let's dive into our first chapter on the APIM fundamentals.

[Music]

Before we talk about Azure API Management, we need some building blocks in place. So, let's talk about what an API Gateway is. And for that, we need to know what an API is. So, looking at the screen, we have a front-end service and a back-end service. This is a traditional programming model when it comes to how a website, which would be considered the front-end service, could interact with a back-end service to get any type of data or functionality that is going to be needed for that front-end service to work.

The front-end service is the visual and what you see. It's a website, it's a mobile app, it's something on your desktop, and it reaches out to a back-end service, typically where there's logic that takes place in order to do that. It uses an API, an Application Programming Interface, using a protocol like HTTP in order to do this.

Another way I like to think about this is using a restaurant example, where the front of a restaurant is the visual that you see. It's the front end of the whole operation, and you have a menu that is your list of requests that you can make to your server. Your server then goes back to the kitchen to make your food and send it back to you, and that is the response to your request. In this idea, the waiter or waitress is your API that allows any type of request from your menu to go to the back end and come back to you.

Now, most applications don't just have one back-end service. A lot of times, they'll be reaching out to multiple back-end services for multiple different functions, and this is without an API Gateway. So, the application would reach out directly to different back-end services, and those back-end services would respond back with any information that the application requested. But the thing is, this can get kind of complicated when we start adding in multiple applications, 'cause then we have multiple applications that are interacting with multiple back ends, and all these back ends might not be the exact same. Some of them might respond with different formats, some of them might not always be functioning properly. These applications might have different requirements because they may be coming from different devices. All these things need to be figured out by each of these different applications or back-end services without an API Gateway, which is why an API Gateway is tremendously helpful.

It takes all of the intermediate logic that happens before a back-end service gets a request, and it changes it and modifies it so that everything can get normalized. It can be governed and controlled so that APIs that come through your API Gateway will only get to the back-end service exactly the way you want it. So, the API Gateway ultimately decouples the logic it takes to interact with the API from the back-end service and puts it in the middle, into this API management solution.

And then, this is where Azure API Management comes in. Azure API Management is a Platform as a Service, enterprise solution that allows you to abstract, secure, manage, and publish your APIs. So, in Azure API Management, you have that Gateway that all the applications make requests to, and all those different services, back-end services, will be in the cloud or on-premise or wherever you have them hosted. Azure API Management has your management plane that allows all of your administrators to make changes and add policies and anything that they want to control or monitor to make your APIs accessible the way you want them so that it fits your requirements and your specifications.

And the developer portal is provided so that the app developers who create the different applications that interact with your Gateway know how the format for responses and requests need to be in order to use the different APIs that they're consuming. So, they will see on your Dev portal all the requirements, subscriptions, products that you make available to them that they can use in those apps so that all of the governance that you have in place for your APIs are followed to a T.

Now that you know the fundamentals of Azure API Management, let's talk about what you need to have set up so you can follow along step by step in the coming chapters.

[Music]

These are the three steps you need to follow before you can get started with the Azure API Management lab. We'll run through them all so that you can check off to see if they're completed or not. You're going to need access to the Azure portal. You're going to need to create an Azure account for this if you don't have one, or you need to request access from your organization admin. You're going to need an active Azure subscription, which you can check once you have access to the Azure portal. When you go to subscriptions, and you'll need a contributor role access or greater to a resource group where you'll create your Azure API Management resource.

First, we'll see if you have access to the Azure portal. If you go to portal.azure.com, it'll take you to the Azure portal dashboard that you have set up if you have one. And nothing shows up, and it looks like you don't have an Azure account, then you might need to create an Azure account. You can go to azure.com to get started with your new account in Azure, where you'll get a ton of free resources right off the back for 12 months and a $200 credit for your first month, and then everything is just pay-as-you-go, but there's still a lot of free options. So, you definitely check that out if you need to create a new Azure account for this, or you'll need to request access from your admin at your organization, and they can go through something like this in order to give you that access.

Next, let's check if you have an active Azure subscription. In your Azure portal, you can go up to subscriptions. Once you go to your subscriptions, you'll be able to see your current role. For an active Azure subscription, you'll see your role, you'll see if the subscription is active, and you'll know that that is the subscription you can use when you're creating your Azure API Management resource.

Lastly, when you know you have access to the Azure portal and an active subscription, you want a resource group that you actually have contributor role access to or greater. So, within this resource group that's currently empty, where I will create my API Management resource, I can go over to access control and within here, I can click this to view my current access. I can see for me, I have owner level access, which is the highest level access you can have because it's my subscription. I can check the roles here to see other built-in roles that exist, where contributor and owner are the two highest roles that you would want for this lab, or you'd want a custom role that is created that has the same level as contributor level access or greater.

Once you've completed these three steps, you're ready to move forward with the Azure API Management lab. If they're still not completed, I've added resources in the description so that you can get started with them now.

Now that your prerequisites are in place, it's time to start building. Let's create an Azure API Management instance, and then we'll verify that it's working.

[Music]

Before we create our Azure API Management instance, let's talk about naming conventions. It's important for you to have a name convention for how you create your Azure resources so that it's quick and easy to distinguish what a service is based on its name. This is the naming convention that we'll use for this lab, where we'll list the service, the environment, the region, the application name, the owner, and then the instance number. For me, this is going to be APIM for the service prefix because that's what we're creating. It's going to be the development environment. I'll be creating it in the East US region. We'll call it the Hands-On Lab or HOL for the application name. Me as the owner is Azure Innovation Station or AIS, and then this will be instance 00001. Coming out, this will be the name of our Azure API Management instance when we create it based on this naming convention. If you want to learn more about naming conventions, I've added a document on its best practices for Azure in the description.

To get started creating our Azure API Management instance, we'll start in our resource group. Right now, I have no resources in this resource group. I'll go up here to create a new resource. I'll search API Management, I'll select it, and I'll get started creating our new Azure API Management instance. Now, you'll select your subscription, you'll choose your resource group, which should already be populated, select your region, and now the resource name based on the naming convention that we've decided upon. I'll have my APIM-DEV-EASTUS-HANDSONLAB-HOL-AIS for Azure Innovation Station, and then 001. I'll just say the organization name is Azure Innovation Station, and I'll choose my email to be the administrator email. Down for the price and tier, I'll choose Developer, that's what we'll use for this lab.

Looking at the other options now, Monitor and Secure, we won't worry about these options now. We might go over them later in the lab, but for right now, to keep things simple, we'll just move on. We won't add a virtual network for this APIM lab, but if you want to see a video with a virtual network installed for an APIM instance, please comment that below. Managed identities allow Azure resources to act as an identity when interacting with other Azure resources through role-based access control. It's out of the scope for this lab, so we won't check it now, but if you want to learn more about it, let me know in the comments. We won't add any tags, and finally, we will review and create our Azure API Management instance.

This deployment will take a while, maybe an hour or two. The reason for this is that Azure needs to set up a specific set of underlying infrastructure resources for the developer portal, the management plane that manages your APIs, and also the API Gateway. All that work together. Take a break or get some other work done, and through the magic of video editing, I'll speed things up so that we can see what's next.

When the APIM instance is done being created, the contact for the administrator that was used during creation will get an email like this, notifying them that it's complete. My deployment is complete, and I can now start exploring my APIM instance. On the overview page for the APIM instance, we'll see a lot of the standard information that you'd see in any Azure resource. What's unique to an Azure API Management instance is the link to the developer portal and also the Gateway URL. The developer portal is where developers will go to see and learn about your APIs, and the Gateway is where API consumers will actually call APIs, and that is the root URL for those APIs is the Gateway itself.

We'll be spending a lot of time in the APIs section over here. In the settings, we can come over, go to APIs, and this is where we'll test to make sure our Azure API Management instance is working. Now, looking at this Echo API that comes with our Developer tier instance of APIM, we can see the operations that are available for this API. We can also test these APIs directly in the Azure portal. So, I'll go to this receive resource, I'll hit send. For this, we'll wait for a moment and see the response below. 200 OK. It worked.

You might be tempted to use the request URL to try to use this in the browser. Let's see what happens when I do that, and it says that it's missing a subscription key. So, it didn't work. A subscription key is what we have by default on all APIs that are created within your APIM instance. Let's go check out this in settings down here. I can see the subscription is required for this API. I can uncheck this box, and we'll save, and then we'll try again to see what happens. I'll open up the network tab, and we'll try this again, and this time we can see that we did get a 200 response. If you want to test the API using another method, I have my Windows PowerShell open here where I'll use Curl to call it and see that it works here as well.

Now that you have a working API Management instance, let's take a look at how developers will learn about and use your APIs in the built-in developer portal.

[Music]

When your Azure API Management instance is first created, your development portal starts unpublished. There's a couple ways to access your development portal, but if a guest were to access it with your development portal link, it wouldn't work. Let's go to an incognito and see what they would see. I can see here that this content has not been published yet. I need to publish it as the administrator first. This is helpful for when you want to customize and make changes to the development portal before it's in use.

Going back to the portal, I can also go to this developer portal link. This will take me to the administrative interface that allows me to make changes and customize my development portal before it's published. This is what it looks like with the different aspects that I can change and customize for my development portal. We'll take a look at this in more detail in a future video.

From the administrative interface, we can also publish the developer portal. Going back to the Azure portal, if I come to the settings, developer portal, and then portal overview, I can also publish it here. Let's do that now. We'll also want to enable CORS. CORS stands for Cross-Origin Resource Sharing. It's a web security policy that prevents web browsers from accessing resources from domains that they do not or originate from. We'll enable this because the development portal will make requests from the web browser to your API Gateway, and we want that to work. I'll enable that now. We'll talk about policies in more detail in a future video, but this CORS policy is actually the first policy that we've now added to our API Management Gateway.

Let's take a look at the development portal now. As a new user, I'll refresh my page in the incognito browser, and here we have our new development portal. Let's sign up with a new user. When signing up, you want to be sure you do not use the same email as your administrator. This wouldn't work because there's already an account using that email. Let's fill out the info and create our new account, and we'll complete sign up.

Next, we need to check our email in order to verify and confirm our account. This is the email I got to confirm my account. I'll click this link now in order to finish activating my sign up. Back in the development portal, I can confirm that a new user account has been created by going to the user section under development portal, and I can see my new user has been created.

Now, let's log in as our new user. Now that I'm logged in, let's explore the products and APIs available to us. These two products come out of the box when you create your first Azure API Management instance. In order to use these, I need to subscribe to the product. I'll subscribe to this by creating a new subscription and I'll just call it starter sub and subscribe. I'll also subscribe to the unlimited product. After filling out the name for the subscription I wanted, I can see that I have an active starter subscription. However, I just see that I requested the unlimited sub. This means I'll need approval from the administrator in order to use the unlimited sub.

Let's go back to the Azure portal and approve the subscription. I can go to APIs, subscriptions, and I can see the submitted subscription from this new user. I'll hit these three dots over here and I'll activate the subscription and confirm. The subscription now shows active from the Azure portal. And going back to the user's perspective, if I refresh the browser, I see that the subscription is now active.

Now that our subscriptions are both active, let's give these APIs a try. I'll go to APIs, I'll go to the Echo API. I can then go to Try It to open up this interactive window which allows me to make API calls from the developer portal to the API Gateway. At the top here, I'll see the subscription key that I'll use will be added in this window for my API call. I'll use the primary starter sub subscription key for this call, and I'll come down and hit send. Because I enabled CORS and because I have the subscription active, I get a 200 response OK from the developer portal to the API Gateway. Let's try our unlimited subscription. I'll select this subscription key and send another request. Another 200 response OK, indicating that it worked.

And those are the basics of using the Azure API Management developer portal. You know how the developer portal works, but what you see is still pretty generic. In the real world, you'll want the styles and visuals to match your brand. Next, let's look at how you can customize the look and feel for your Azure APIM developer portal.

[Music]

Starting in the Azure portal, there's a couple different places you can go to navigate to your APIM developer portal. The development portal can be found at this URL. This is the URL you would go to if you were a guest or if you wanted to give a guest or someone access to the developer portal to begin using it. However, for us, we want to log in as the administrator, so we'll go and use this link up here. This administrator interface is where we'll make changes and customize our development portal. We have a list of visual editor menu options that we'll go through within this video. You can see different pages based on who's logged into your development portal, so we can check out what it looks like from a developer perspective and also from an administrator's perspective. And we can see different screen sizes for our development portal to understand what our development portal would look like with different devices.

When we want to make changes to a page, I can click into the page and see different visual editor options appear. As I hover over icons, I can make changes to this text by hovering above it, clicking edit text, and making changes right in the editor. I can then hit save, and now this is a new part of my development portal. However, these new changes won't occur until I publish the new development portal.

The first item we can customize is our different pages. Each page within your development portal has a unique URL. We'll create a new page now. We'll call it our secret page because right now it doesn't go to anything. We'll save this and we'll go to our secret page. Here we can make changes to our secret page and edit any aspects we want. When I'm done making changes to my page, I can close this, and my visual editor will open back up.

I see here at the bottom, I have this "Powered by Azure API Management" and I also have this Koso image and the nav bar here. When I click onto my screen to make changes, I hover above the Koso or the nav bar or even this footer, and nothing appears. I can't make changes to it. That's because it's using the layout. There's two layouts that are used, but these are the aspects that can be added if you want to have a page on top of a layout that is common across many pages. This default layout is used for anything beyond the homepage.

Let's create a new layout for our secret page. I'll call it secret layout, and it will work for our secret page. So, I have to use this secret page URL, so our secret page knows to use it. I'll refresh this for our secret page, and I'll see that our secret page is now using the new layout. I want to add a footer to the layout for my secret page, so I'll go to the layouts, secret layout, I'll click into here, and I'll add a new item. It's just going to be a blank article where I'll add some text. I'll edit this text. I'll put it in the middle here, and I'll make it a little smaller to the size of a styled footer.

After customizing pages and layouts, the next thing you can customize is your menu and nav bar items. When navigating the nav bar and menu options, there's different items that are only available based on users who are logged in. Let's create a menu option to get to our secret page for only authenticated users. We'll come up to here, add new item, and we'll just call it secret. We'll link it to a page, and we'll select our secret page, and then assign the location for the menu option. We want to add it to the authenticated user menu, so all users who are authenticated will see this along with the reports, profile, and sign out options. And we'll have it open the same window. We'll save this.

Now, if we go back and we go to our pages and we go home, we can view this as a developer and see our secret option. Something else that's important to know is that when you're using the developer portal, if you ever want to navigate it as if you are an actual user, you can hold the control key on Windows or the command key on Mac. Here, I'll hold the control key on Windows, and as I hold it, I can hover above these icons to see the colors change as if I were a user. If I let go of the control key, I have the option from the visual editor to make changes to the nav bar. Holding the control key, I'll navigate to our new secret page, making it not so secret anymore.

Closing this and looking back at our nav options, I can also change the order in which these appear. If I want my secret menu option to appear earlier, I can use these little carrot keys for it to appear before the other options. Going back to my homepage, I can see the secret option appearing earlier in these nav bar options.

Next, let's check out how you can customize URLs. These URLs will help you create links to external websites if you have services or resources that you want to send your users to. I'll create a link to the Azure Innovation Station website, and we'll create a link to that on our secret page. Let's go to my layout that has the "Powered by Azure Innovation Station" and let's add a link to it. I'll hover above it, I'll make a change to this text. I'll highlight the text that I want to add the link to, and I can hover above this icon set hyperlink. Then, within these hyperlink options, I've got a couple different things that can go to different pages, image, a popup, or in this case, a link. I'll select my Azure Innovation Station link, have it open up a new window, and I'll save it. From here, I'll hold the control key to navigate to my secret page, and then I'll hover above my Azure Innovation Station link and I'll click it to go to the Azure Innovation Station website.

Next, let's look at popups. Popups are the floating windows that appear on websites when there are certain actions that the website wants you to take as a user. There's a variety of great reasons to use popups, and in this page right now, there's one popup. I can look at the settings for this popup and open it up and see this looks like the navigation bar for when the screen is too small for the development portal to list the nav bar options on the top of the screen. If I want to see this in action, I can view the development portal at a smaller size, see the hamburger icon, hover above it with the control key, click it, and see this popup appear.

Now, let's create our own popup. I'll close this. I'll add a new popup and I'll call it my popup. I want to make a change to my popup, so I'll edit it by opening it up here. I'll hover above this. Now that I've made changes to my popup, let's create a button on the home screen that'll make it appear. I'll hover above this button and I'll add another button next to it. This button, I'll change the name for Eder button and I'll just call it popup button. I'll make the button trigger a popup, and the popup it'll trigger is my popup here. The popup will open when I click on it. You could also have it open when it hovers. I'll then open up the popup to see what it looks like, and there it is. I'll close it. I'll hold control again to navigate in the page as if I'm a user, and I'll click on the popup button. There's my popup that appears, and I'll close it again.

Now, right now I have this Koso image that appears on the top left of my development portal. I want to change that to my logo, the Azure Innovation Station logo. So, I upload a media file, which I can do here in the media section. I've uploaded my image. Now, let's replace this with my picture. It's a little big. I'll change the width and height, make it fit better.

Next, I can change styles to my development portal. This styles page helps you customize a lot of the different elements of your development portal: the fonts you use, the colors you use, the buttons, and more. Let's create a new color and button variation for our popup button on the home screen. I'll click add a color here. We'll make it a light green. We'll call it light green, very original. Then, we'll come down to buttons where we'll add a button style. We'll call it our green button, where our green style button will adopt our color green. So, now any button that I choose to give the style of green button will appear like this. Let's save this and make this change to our popup button. I'll edit button and I'll give it the appearance of the styling of our green button, and I'll save it. Now, holding the control key, I can see that my green button is green. I can still click it for my popup to appear like before.

If you want to take customizing your development portal to the next level, you can also create custom widgets. These custom widgets allow you to create custom code to add functionality to your development portal. Adding a custom widget is beyond the scope of this video, but if you want to learn how to do it, let me know in the comments.

Lastly, we have our settings for the API Management developer portal. I'll change the title of the web page to be AIS Dev Portal for the Azure Innovation Station Dev portal, and I'll save it. I want to view these new changes to the developer portal as a guest user. Let's open an incognito browser and navigate to our developer portal to see what it looks like. I haven't published all the changes I've made to my developer portal, so first, we'll look at it as it currently exists. I'll open up a new incognito browser, I'll navigate to my developer portal, and this is what it currently looks like.

Now, let's publish the developer portal, and then we'll wait a few moments for the changes to take effect. After a few minutes, I can refresh the page, and I should see the changes to my new development portal. I've refreshed my page, and this is my development portal with the changes I've made. I see my image and I see the popup button here.

The last thing that you need to know when customizing your development portal is how to reset back to the defaults if needed. If I go to settings and advanced, I can reset to the default styles that the development portal gave me when I first created my Azure API Management instance. Be careful when doing this, 'cause once you do, you can't revert back to all the styles that you had before. And that's how you can get started customizing your Azure API Management developer portal.

Now, when people visit your developer portal, you can have a look exactly the way you want. But when a user signs up, they're still getting a generic email notification. So, next, let's look at notifications and how you can customize them in your Azure APIM management instance.

[Music]

Starting in the overview page in the Azure portal, we can go find notifications within the deployment and infrastructure menu. Come in here, deployment infrastructure, scroll down, and we have notifications and notification templates. Notifications are the notifications that administrators and people who are working on the APIs get when any of these certain events occur, and their emails are associated with those events. The notification templates are emails for developers and API consumers when any of these events occur. These are notifications that they will get.

When looking at the events that just the administrator sees, you can choose to view these different events by just looking at the title or the description. We can toggle these in order to see just one or the other if we didn't want to see both of them at the same time. I'm fine seeing them both. The different kinds of events that exist are things like when a subscription is requested from a developer who wants to use one that requires approval, or if someone closes their account for the developer portal. An administrator could also decide to just be BCC'd on every single developer notification that is sent.

To get notified of any of these events as an administrator or someone working on APIs, we can click any of these events and we can add an email for someone who we want to be notified when these events occur, or we could add the admin email. I can just click this, and my administrator email will be added. Now, anytime a subscription that requires approval is requested, I'll get a notification about it.

I'm in the developer portal now in an incognito browser, logged in as a user. Right now, you can see I have no subscriptions for this user, and so I can come over to products, I can go to the unlimited product, and the unlimited product requires administrator approval to start a subscription. And because of this approval, the administrator will be notified because of that notification set up. I'll request to subscribe to this, and I can see here that it's submitted and I'm waiting on it to be approved. Because we set up the notification for the administrator to get notified when a new subscription is requested, I got this email here, where in this email we can see that Frank Riviera submitted a subscription request for the unlimited API product.

Back in the Azure portal, let's take a look at the notification for developers. I'll come to notification templates and I'll see all the different kinds of templates that are already set up for notifications for developers. One to point out is the subscription request received notification. As a developer in the incognito browser, we just submitted a request for the unlimited API to get access to it. Let's see if we got a notification confirming our request was received. And sure enough, we have our request received notification as a developer.

Back in the Azure portal, and because these are notification templates, we have the ability to customize and change these emails when they're sent to developers. I'll open up the new subscription activated email template. We can see over here these parameters. These are parameters that you can add to the email template that are already pre-defined and available for these specific notification templates. To make a change to a notification template, I can simply click inside of the notification template itself, and I can make any changes, and I can also add a parameter if I choose. Now, it should say "Hello," and then the developer's first name here with the parameter, and then anything else after.

I have taken the liberty of making changes to this template already, adding in the parameters that are available for this template. So, when this developer gets this new subscription approved, they'll get this notification email about their new subscription, and we should see the list of parameters that I've added to this custom notification template. Let's save our template and go approve the subscription for the developer.

Under subscriptions, we find this submitted unlimited subscription. We'll come here to the three dots and we'll activate subscription, confirm. Now, the developer should have gotten a notification email about their new subscription that's been activated. And here's my notification email that I got as the developer. I can see down here the different parameters that I added, so I can see what the name of each of these parameters is. I added an escape character so that I can actually see what the name of the variable names are when customizing the email templates, and then I added the HTML tag strong to make it bold, so we can see what the actual parameter comes out as.

After refreshing my developer portal, I now see the developer has a subscription for the unlimited product. Back in the portal again, the last thing to point out when it comes to notifications is the email settings. The email settings has your administrator email, your organization name, and the originating email that will send all the notification emails. Both the administrator email and the organization name are set up when you first create your Azure API Management instance. The originating email is the default for all emails that are sent. If you want to change your originating email, note that your emails will likely still have this as the originated email because Azure API Management still will technically send the emails.

To show you an example of how this works, earlier I did a test by changing the originated email to be the same as my administrator email. I made a request as a developer for the unlimited API, and this is the email I got with my originated email having changed. I can see up here that I have the administrator email that I added as the originated email, but I still see that the email that actually sends the notification is the default email that Azure API Management uses. This should help you get started with notifications for administrators and developers in Azure API Management.

Now that your developer portal and email notifications are looking like your brand, we want to start adding APIs. To start organizing your APIs, you need to add them to a product. Next, let's learn about how Azure API Management products work.

[Music]

When talking about how products interact with APIs in your Azure API Management instance, we can think about your APIM instance with a sort of API store, which has a variety of APIs that are available. The APIs that have been added to your Azure API Management instance can then be added to any specific product that you have so that developers can subscribe to products and get access to the APIs you've specified. For example, I could create a product one where I make all of the APIs that I have available within that product. I could also create separate products where only specific APIs are available for those specific products, meaning a developer might subscribe to a product but only get access to the API that we've specified for that product. And there's a lot of options for managing your products as you go, where you can add APIs to your products and remove them whenever you want.

In the Azure portal, let's navigate to our products and see what we currently have. If I come over to the API section and in the dropdown click products, I can see that we have two products currently: the Starter product and the Unlimited product. I can click into these products to see the different settings and features available for them. Going into settings, I can see that this product has a rate limit of five calls per minute and 100 calls per week. Let's see where this is. If I go to policies and come over to inbound processing, I can hover above this and see that it has a rate limit, and this is where our limit of five calls every 60 seconds comes and our quota for 100 calls a week. We'll go into more depth on policies in a future video.

Going to the APIs property, I can see all the APIs that this product has associated with it. Going to the subscriptions tab, we can see and manage all of the subscriptions that are specific for this product. The Unlimited product requires administrative approval. We can see this in settings from when the product was first created.

Let's create our own product now. Within products, I'll click add, and we'll call this product our Gold Tier product. We won't publish it just yet because I may want to make changes to my product before it's available to developers and guests. I'll require subscription to use this API so that it's more secure, but I won't require administrative approval for someone to subscribe to this product. The subscription count limit will help you optimize the performance for the APIs within your product if you don't want too many developers subscribed to the product using those APIs. I won't have a subscription count limit for my Gold Tier. You can also add legal terms for your product if you want developers to check a box saying that they agreed to the legal terms before using your product.

I also have the option to add APIs to my product while creating it. I'll add the Echo API and create my product. My new product is created, but I can see here that only administrators have access to my Gold Tier. I want to change this access control so that developers and guests will be able to see my Gold Tier product as well. Going into the Gold Tier, I'll select access control, I'll add a group, and I'll select developers and guests to give them access to my product.

In a new browser window, as a guest developer, I can just see the Starter and Unlimited product. If I refresh the page, I still don't see my Gold Tier product, but the reason for this is because my Gold Tier product still is not published. Back in the Azure portal, let's publish our Gold Tier now. I can come over to the three dots and I can hit publish. Back in the other browser window, I can now refresh the page, and I can see my Gold Tier product available.

This should be all you need to get started with products in Azure API Management. Now that you know how products work, let's add our first API. We'll add it from scratch so you can see how it works step by step.

[Music]

To begin in manually adding an API, we'll start in the Azure portal overview page for your Azure API Management instance. We'll navigate to the APIs dropdown and then to the APIs page. Within here, we can see a handful of the different options we have to define new APIs. We'll add a manually defined API now. We'll there's basic options if you want to fill it out quickly, but we'll use the full options to look at all the details.

The API we'll be adding is called the Star Wars API. You can call it to get data about Star Wars characters, planets, and ships. To see an example of how this works, we see this endpoint that they have for the Star Wars API where we can then add something like people/2 and get C3PO. I'll add a link to the Star Wars API in the description. Let's add this Star Wars API now. I'll copy the endpoint for the Star Wars API to my clipboard because we'll need it when we're manually adding it to Azure API Management.

To begin creating the API, we'll start with the display name and the ID name in the description. The web service URL is the URL for the back-end service. We'll paste this from a clipboard. It's HTTPS, and the API URL suffix is to help us not have any conflicts when calling our Azure API Management instance. For example, this is our base URL for Azure API Management. If we want to call the people endpoint for our Star Wars API without a URL suffix, then our call would be this base URL with /people to the Star Wars API people endpoint. But if we had another API that we added, say a public Marvel API that gave us data about Marvel characters, then we might have another API that also ends in /people. This would be a conflict, and we wouldn't be able to do this. So, using the suffixes, we can have SW for people, and for the Marvel one, it could be something like /marvel/people. That said, we'll add SW for our API URL suffix.

Tags help you organize and manage your APIs. These are not the same tags that are associated broadly with your Azure resources. These tags help you specifically filter and find APIs in Azure API Management. You can create tags in the API tag section when you're creating APIs, you can add those tags then to those APIs, and then when you're searching or filtering for APIs, you can do so with tags. These are separate from the tags that are associated with Azure resources. For what we're doing, I won't add any tags here.

To use my API, I need to add it to a product. So, I add it to my Gold Tier, and I'll use the managed Gateway instead of a self-hosted or self-managed Gateway. It's good practice to version your APIs, but we'll talk about versioning in a future video, so I won't click that and manage that here. I'll create my API now, and we see our new manually created Star Wars API.

There's no operations to it, so let's create a few operations. We'll start with a GET people operation to get all of the characters in Star Wars. Generally, it'll be a GET request. It's the people endpoint. Have a description of "get people." This is good. We'll save this and create the next operation.

Now, let's create a GET people by ID operation. It'll be GET people by ID. It's a GET, and this time we'll add a URL template parameter for ID. When manually adding operations for an API, we have some options to give defaults for URL template parameters, query parameters, headers, and even example requests and responses. In this case, I just have a template parameter for our ID. I won't add any defaults in this case. We'll save this, and we now have two operations for our Star Wars API.

In a new browser window, I've logged in as a user to the developer portal. Let's give our Star Wars API a try. We'll try to get people with our Gold sub attached. Come down, send. Injured response OK. Let's give our GET people ID a try. It does require an ID for our character. We'll do two, send request, and we get C3PO back. Awesome. 200 OK.

And this should be all you need to get started manually adding APIs to API Management. You just added your first API, but in the real world, it would take way too long to add APIs one by one like this. So, next, let's look at how you can import a set of APIs using the OpenAPI specification.

[Music]

We'll start in the overview page of the Azure portal. We'll navigate to the API dropdown, the API setting, and we will add a new API. In our last video, we created an API manually by plugging in all the information we needed to create our API in our Azure API Management instance. In this video, we'll be adding an API using an OpenAPI specification. The OpenAPI specification allows APIs to be added with multiple operations all at once. It's a standard that's been around for years now, and if you want to learn more about it, I'll add a link to it in the description.

The API we'll be adding is this simple calculator API. It has operations to add, subtract, multiply, and divide. Something to point out with this API is that this "not secure" warning indicates to us that this API is using HTTP, whereas most APIs these days use HTTPS. HTTPS allows for another layer of security so that data that's sent to and from an API that's using HTTPS is encrypted. When we use this API, API consumers will make requests to our API Management Gateway via HTTPS. Then, we'll forward requests from the Gateway to this API into HTTP so that we can use it. Responses will go back to the API consumers through the Gateway using HTTPS. This is an example of one of the powerful things that Azure API Management can do for us. By having our API Management Gateway as an intermediary between API consumers and backend services, we could have a backend service that's working great using HTTP and then later upgrade it to HTTPS without API consumers ever knowing.

To import this calculator API, we need to upload the OpenAPI specification doc. This is the OpenAPI specification doc URL. I'll add a link to it in the description. This doc gives us an example of

What some of these operations will do, I can see I have a path ad with two URL parameters. It adds two integers, and I can also see that there are two default values associated with this operation.

Back in the portal, let's import our calculator API. Now, I'll open this to add from Open API definition. I'll see the full details. Note that my display name, my description, my name are not filled in currently, but when I add my specification doc, they all get brought in. The URL scheme will need to select as both. We want the developer portal to send requests using HTTPS, but we want our backend service to use HTTP. Our suffix, we'll call it calc. We won't add the editing tags, and we'll add this to our gold tier product, and we'll create this.

Once we've added this API, we need to make sure in the Azure portal that these requests are being forwarded using HTTP. Right now, I can see that it's using HTTPS still. So let's go to this pencil icon. Let's make this change, and we will override the service URL to make sure it sends using HTTP. This is important because this old API that hasn't been upgraded to HTTPS won't work if you don't make this change.

In a new browser window, I've logged in as a user to our developer portal. Let's try our basic calculator. I'll go to add two integers. My gold subscription is added, and there are two default parameters, 51 and 49. When I go to send request, they should add them, and I see here that I have a value of 100 as my response. So this worked.

At the time of recording, there's a bug with the dropdowns in the developer portal, so we'll need to get rid of the defaults if we want to use other values. To do this, we'll go over to the Azure portal. We'll come to add two integers, hit the pencil icon. I'll pop myself to the left side of the screen, and we can see here the default value 51 and 49, and we will get rid of these default values so that there's no default value. And we'll save this.

Trying this again in the portal, I'll refresh the page and see that there are no values. So I'll add something like 30 and 25, which should make 55, and I can see here 55. Have our new value, but this is still a problem for the other operations for our calculator API. So this time, let's go change the specification doc so that all of these values can change at once.

Back in the Azure portal, I'll go to my basic calculator and under all operations, I'll make a change to the Open API specification doc. We'll come down to subtract numbers and we'll get rid of these defaults in this default value, and we'll do this for the other operations. Now, when we go to these other options, we should see no default values for them as well.

Back in the developer portal, I can see that the values are gone, and I can multiply 2 * 4 and get eight. So that worked. This should give you everything you need to get started importing APIs using an Open API specification in Azure API Management. Importing APIs from spec docs is great, and if you're using Azure for backend services, you can import APIs directly from existing solutions.

Next, let's learn about how you can import an API from an Azure OpenAI endpoint and an Azure function.

Starting in the overview page, the Azure portal, we'll go to our dropdowns, APIs, and then our page, APIs. In our last two videos, we manually added an API, and we added an API from an Open API specification. In this video, we'll be adding APIs from an OpenAI resource and a function app resource that already exists within Azure.

Let's start with Azure OpenAI. To create this API, you already need to have an Azure OpenAI instance with a deployment already set up. Going over that is out of scope for this video, but if you want to learn how to do that, let me know in the comments. I'll select my OpenAI instance. The API version for Azure OpenAI needs to be listed. This is the latest default version, so that's the one I'll use. The display name, I'll call this APIM D OpenAI. For our base URL, our suffix for our OpenAI instance will be the same as our name ID. There's also the option here to add slash OpenAI at the end of our base URL because a lot of recent AI SDKs expect OpenAI to be at the end of endpoints then they call them. We'll add that here so API consumers can use those SDKs, and we'll add this to the gold tier product.

There are some policies that we can take a look at when adding this API. These policies allow us to control and view token data when API consumers are using them. I'll add this manage token consumption policy, which allows me to limit how much tokens API consumers can use. I'll also add headers with these checks so that API consumers can see how much they're using and how much they have left. I won't add the track token usage because it requires an Application Insights instance, and we'll go over how to add an Application Insights instance to Azure API Management in a future video. I'll review and create and create it.

When I add an API from an Azure OpenAI resource, the API gives me several operations. My deployment for Azure OpenAI is meant for chat conversations, so while these operations might work with different models, my deployment will work with this first operation.

In a new browser window, I've logged in as a user to our developer portal. Let's try this Azure AI API. Now, for this first operation, it requires a deployment ID. This is the name of your deployment that you can find in your Azure OpenAI Studio or your Azure AI Studio. I've opened Azure AI Studio here, and we can see this is the deployment that I'll be using for this API call. If you're curious about Azure AI Studio, you can find a link and a video on how to get started in the description.

Back in the developer portal, I'll paste in my deployment name for the deployment ID, and I'll use the same default API version that I used when I created my API in API Management. There's a default request body, but I pre-created a default request body that I'll use where my request body tells my AI to act like a pirate and talk about fun facts about the world, and I ask it, "Why is the sky blue?" Let's send this request and see what we get. We get a 200 OK, and our answer about the sky being blue is here.

Back in the Azure portal, let's add an API from an Azure function resource. I'll create an API from a function app resource. We'll see the full definition, and I'll select a function app by browsing to select one. I select my functions demo function app, and I only want to use my random color HTTP triggered function. I'll change this to random color and make my suffix Rand color. There will be no tags, and I'll add this to my gold tier. I'll version this API, and I'll create it.

Back in the portal as a user, let's try our API that calls our Azure function that gives us a random color. We'll go to get random color and give this a try and see it comes back blue or red or green.

This should be everything you need to get started using Azure OpenAI in Azure API Management along with Azure functions and other Azure resources. You've seen all the ways we can add APIs, and we've done some basic testing in the developer portal. But users will not always be calling your APIs from that portal. So next, let's learn about how you can call an API using subscription keys and endpoints.

To practice calling APIs, we'll use this colors website that allows us to make API calls directly to an API of our choice using. If I come up to this hamburger icon and I click config, we're going to import an API that will then add to this website to make calls to our API Gateway using our subscription keys. This is the Open API definition for the API we'll be importing. You can see up here it says Swagger on it. That's because Swagger is an old name for the Open API specification. I'll add a link to this in the description.

In the overview page of the Azure portal, we'll go to our API dropdown, our API page, and we'll create an API from an Open API definition. We'll open up the full. We'll add our Open API specification. It'll fill out some info. We'll add this to our products starter and unlimited, and create this.

Before we can make calls from the colors website to our API Gateway, we need to make it an allow origin using CORS. I'll come over to our CORS policy. I'll hit the pencil icon, and in the allowed origins, I'll add my colors website. If you want to allow all domains, you could add the star icon and save it, and all domains could call your API Gateway.

In a different browser window, as a user, I've logged into the developer portal. Now, let's test our new colors API. I'll come to our colors API and I'll try the get random color. Send a request, and I see it comes back light blue random color.

Now, let's use our URL with our colors website. I'll copy our URL which goes to this random color API endpoint. In our colors website, I'll add the URL here and I'll submit this. Now I'll start it, but it shouldn't work. There's an HTTP 401 error because we're currently unauthorized to make calls to this API without a subscription key.

Back in the developer portal, let's grab our subscription keys. I can come down and I can see the keys for our unlimited sub, our gold sub, and our starter sub. Let's practice using the starter sub and using the unlimited sub because we know with these two products, the starter sub only allows five calls a minute, while the unlimited sub allows an unlimited amount of calls. I'll add the URLs with subscription keys to the end in a notepad so I can easily copy and paste them over to the colors website. Please note that you should never share your subscription keys with someone else publicly. I'm only allowing you to see it now because by the time this video gets published, these will be deleted.

Back in the colors website, let's call our random color using our unlimited subscription key. I'll add it here. You can see now I have the subscription key at the end. I'll submit this, and then I'll start it, and we can see each one of these calls occurring over and over. If I stop this and now switch out the same call, but now using our starter subscription key, we're keeping in mind our starter subscription only allows five calls a minute. We should see this stop after five calls, and we see after five calls, it had a failure.

If I copy and paste that random color API with our starter subscription key, we can see that our rate limit has been succeeded because it only allows that five calls a minute and 100 calls a week. You can continue to play with this colors API and the colors website, but this should give you everything you need to get started calling APIs and using their subscription keys.

Now that you know how APIs will be called, let's learn about how you can modify the behavior of those APIs using Azure API Management policies.

What is a policy? Well, an Azure API Management policy is a statement that, when implemented, will modify the behavior of an API. These policies can take place at multiple different levels or scopes. There is the global scope that all APIs can get policies applied to. There is the product scope where you could apply policies to a specific product. You could also apply policies to a specific API, and you could also apply policies to a specific operation on a specific API.

You can apply a policy to any API request by adding to the inbound section at any of these different levels. Similarly, you can apply a policy to the outbound section at any of these levels to affect the API response. There is a backend section for the policies that's reserved for forwarding a request or the forward request policy, and there's also the ability to add policies when there's an error from the backend service.

Policies are in XML format, and we can make changes to the way our policies are executed and configured by adding C# expressions. These C# expressions get access to the request or response context that we can then use to modify our policies. Here's an example. In this XML snippet, we have a set header policy where the value for the header that's being set is coming from the access we have to the context variable. This context is giving us access to the user ID and the region that the deployment for the Azure API Management instance is currently in.

We can also determine the order in which our policies take place by taking advantage of the base element. This base element represents the policies that take place at a scope above the current scope. For example, let's say this XML snippet takes place at a product level, where the only level above it is the global level. Policies take place from top to bottom. So when the inbound policies execute, the product cross-domain policy would execute, and then because base is after all of the global level inbound policies, it would execute, and then this product's find and replace policy would then execute.

There are a lot of policies, and in the coming videos, I'll show you how you can implement several of them. Let's look at where these policies take place at a global level. At the APIs page, I can select all APIs to make changes to APIs at a global level. If I want to make changes to APIs at a product level, I can go to products, I can select a product, and then I can select its policies. This is where I can make changes to policies at a product level.

Going back to the APIs, if I want to make changes to an API level policy, I can select an API, and as long as all operations are selected, I'll make changes to policies at an API level. And if I want to make changes to an API operation, I can select an API operation and make changes to policies at an API level.

Now, let's add a policy and see it in action. This get random color operation allows us to get a random color. I can send it multiple times and get different kinds of colors. But say I wanted to get the same color for a period of time, I could add a caching policy. Let's do that now. I can come over to inbound processing. I'll click add policy, and I'll see a list of different types of inbound policies I can add. I want to add a cache and response policy.

When adding the caching policy, I have the option to just add how many seconds I want the response to be cached. I also have some more granular permissions if I want to add those as well. I'll stick to basic, and I will just add a 15-second caching policy. I'll save this, and I can see now that the cache lookup has been created, and also this cache store has been created.

If I want to see what this looks like in the XML format, I can hit this policy code editor icon, where I can see the inbound cache lookup and the outbound cache store, which will take place for 15 seconds.

To see this working, we have a colors website that will make calls to our random color API and display the color it gets in response as a random dot with the color that it gets back. Normally, without that caching policy, we could have this request go, and there will be random colors that it gets in response all across these dots. With the caching policy, we should see the same color across the randomly selected dots for 15 seconds.

If you want to see how this works, in our last video, we showed how you can go to the config settings for this website and add the API URL that you can find as a user on the developer portal with their subscription key from their profile. Note: you should never share these subscription keys with anyone. I'm only showing you mine because it won't exist when this video is published.

Now, let's see this work. When I start this, I should see the same color for about 15 seconds, and I see the same color being used, meaning our caching policy is working. These are the basics of Azure API Management policies, which are a big part of what make the service so valuable. In the coming videos, I'll be going over more examples of how to implement other policies.

As you can see, policies in API Management are pretty helpful. So next, let's learn about a specific set of policies that are so valuable, we've dedicated a whole chapter to it.

There are five categories of transformation policies that we'll go over. I'll share some scenarios for each one that give you an idea of when it may be put to use, and then I'll share a demo for each category by implementing a transformation policy.

Find and replace transformation policies are the most self-explanatory. Anytime you want to find and replace information on an API request or response, you can do so with this policy. In the Azure portal, let's implement a find and replace policy. I'll go over to APIs, my APIs page, I'll go to the colors API, and we'll go to the get random color API. Right now, when I test this get random color API, it will return a color with blue in the name of the color output. If I send this a few more times, you can see light blue, blue, dark blue, lots of variations. Let's replace this with yellow by using a find and replace policy.

So in the get random color operation, I'll go to design. I'll go into the outbound processing where I'll select the policy editor. I'll expand this, and after base, I'll show snippets and I'll select the find and replace string in body transformation policy, where we'll look to find blue and replace it to yellow, and I'll save this. Now I can see in this get random color operation the find and replace policy in place. When we test this now, we should see blue get replaced with yellow, and there's an example, dark yellow, light yellow, whereas that was blue before.

Conditional transformation policies are policies that will be implemented and executed only when certain conditions are met. Let's add a conditional policy. Within my Star Wars API, let's go to get people by ID. In the get people by ID operation, when I test this, let's put in, we'll put in one. I can see a variety of information that comes back. Luke Skywalker has a handful of properties that's returned. Say I had information that I wanted to only provide certain developers based on the product that they were using. Maybe there was different pricing tiered products that I was offering to developers and other API consumers, like a smaller package and then a larger package that they'd pay for that would give them more information. Let's create a conditional policy that'll remove some of this data unless an API consumer is using a specific product.

Let's go to the get people by ID operation and we'll create a policy going outbound. Under base, we'll paste this code. You can find this snippet of code either in the Azure API Management Hands-On Lab or in a GitHub gist that I'll include in the description. What this transformation policy does is that when the request is 200 OK and the product is not unlimited, then we will remove the hair, skin, and eye color and gender properties.

First, we'll try it with the unlimited product subscription, where we should see the property still there. Then we'll try it with a different product subscription, where we should see the properties removed. Coming to test, we'll choose our product unlimited. Send a request. Oh, we got to start with number one. Could be any value, but we'll still use the same characters before, and we can still see our hair color, skin color, eye color, gender. This information is still there. Now, let's choose a different product that'll use a different subscription, say our gold tier. Send the request. Let's see if that information is still there. It's not. Now the information is gone. The gender, eye color, hair color, that's all been removed because of our conditional transformation policy we put in place.

Content modification transformations are when you want to change the content of your API request or response in some fundamental way. Let's add a content modification policy. I'll go over to my basic calculator API. I'll go to add two integers operation, and when I test this, let's add three and five together, which makes eight. I can see the output here listed as an XML format. Say I wanted to convert this XML to JSON. There's a transformation policy that'll help me do that.

Let's implement this by going to design, go to add two integers, and then the outbound processing policies. We'll expand this. Under base, let's open up the snippets and find the convert XML to JSON. I have a handful of different attributes that can be altered for this policy, and I won't want it to be JavaScript friendly for specific forms. Instead, I want to convert directly, so I'll use the kind direct attribute. I want to always try to apply this conversion. This last attribute is to consider if there is a JSON header being requested in the request headers. I don't want to care about this. I want to try and convert regardless of the headers that get sent in the request. So we'll save this, and now we'll give this a test. Let's add four and four together, and now I can see that my response is in JSON format.

Transformations that involve adding and removing headers are done for a variety of reasons. Better security, better performance, better user experience are a handful of drivers that would make you want to use these policies. As part of our fourth transformation category of adding and removing headers, let's remove two headers now and see how that works using transformation policies. In this response example, adding two integers, we see this ASP.NET version and this powered by header. Let's remove these using transformation policies.

I'll go to design, I'll go to to add two integers, and I'll go to the outbound processing policies. Let's expand this, and down right after our XML to JSON, let's add set header. We'll put in those policies, ASP.NET version, and for the existing action, I will just delete this. I'm not adding a value, so I'll close this. Let's add the next one, powered by, and save this. Now let's give this a try. When I test this, we shouldn't see those same two values come back, and sure enough, the values should be right here, but they're not because we just removed them using transformation policies.

The last category of transformations is when you want to modify existing headers or query string parameters. Just like adding and removing headers, there's a variety of reasons why you may want to use this transformation category. So far, a lot of our transformation policies have been occurring in the outbound section of our policies. Let's create a header and a query string parameter that are sent in the inbound section so that our backend will get this new header and a query string parameter that our API management instance adds to the operation that's sent.

When adding policies to the inbound section, we don't always know based on the response if those policies on the inbound section executed properly. That's why when testing your APIs, there's a trace feature that allows us to see the whole request response cycle that occurs within Azure API Management. Let's check out what it looks like before we add the inbound policies, and then we'll look at it after.

Within the add to integers calculator operation, let's send a request and see what it looks like using trace. I'll add three and six together, and I'll select trace instead of send. I can see it's 200 response OK, and because I hit trace, I can see this full lifecycle. What happens in the inbound section, the request that ends up getting forwarded to the backend service, what happens in the outbound section, and if there's an error, what gets executed within the on error section. Within the inbound section, I can see the information that comes in with the request. I can see some CORS operations that happen at our global policy level. I see this backend service being set because the calculator API needs to use HTTP, and I see the request that ultimately gets forwarded to the backend, and with along with all of its headers and the URL. Coming to outbound, I can see my XML to JSON policy that we executed, and also our set header policies that removed the headers that we wanted to remove.

Now, let's add a query string parameter and a header in the inbound section so that when we forward our request to the backend, we see a new query string parameter and a header within the header section. Going to design, add two integers, policies, within the inbound section, we'll expand this. Under base, let's open up the snippets and go to set HTTP header. We'll call it X region data. If there already exists this header with the same name, we'll override it with this new value. Let's use the context variable to get access to our deployment and region. Let's add a query string parameter. I'll show snippets again, set query string parameter. Let's call it X product data. If there is a query parameter with the same name, we'll overwrite it, and the value, we'll use the context variable again to query the product that is being used for this request. What our context variables are doing is that if there is a product being used for this particular request, then the name will be given here as a value. Otherwise, it'll be given a name of none, and this context.deployment.region will just list the region that our API management instance is deployed in. Let's save this, and we'll give it a try.

Going back to test for adding two integers, we'll need to run the trace again. Select trace, and then in the inbound section, let's see if our policy is executed properly. I see our set query parameter where first our expression was evaluated and executed, and then our query parameter was then actually appended to our URL that we'll send to our backend service. Next, we see our header that first is evaluated using the expression, and then is actually added to our backend service as a header. If we look at the forwarded request to the backend, we can see our query parameter that is sent to the backend service. Then further down here, we see our new header that we created and sent to the backend.

This should be everything you need to know to get started using transformation policies in Azure API Management. You've seen the power of policies, many of which use C# expressions to function, but what if you had a complex expression that you didn't want to keep typing out over and over again, or a secret that you didn't want to hardcode into a policy? It'd be nice to have a custom variable that we could store these values in and reuse over and over again. This is why our next chapter of our journey takes us to named values.

An Azure API Management named value is a constant created to protect secrets, to reuse expressions, and to enhance API organization. There are four main reasons to use named values: You create them in one place in your Azure API Management instance. You can reuse them multiple times throughout APIs, products, backends, anywhere you need. You can have additional security with secrets being encrypted within Azure API Management, and you can even pull secrets from Azure Key Vault. It's also easy to maintain if you have naming conventions, semantics, references that you want easily propagated throughout your whole Azure API Management instance.

Here are four examples of when you might use a named value: If you have different environments, you might have connection strings or API endpoints that you want to swap out and change depending on the environment that you're working in. If you have API keys or secrets that you don't want to hardcode into API policies. There may be dynamic data that you want where you need a C# policy expression that's constantly changing, and you don't want to write the expression down every single time you use it. You might have a feature that you want to just switch on and off with a named value, using it as the feature flag.

Now, let's create a named value where we want to send an HTTP header to a backend service with the exact time and date that the backend service got the request. We'll need a C# policy expression for this, and we want to be able to reuse this without having to rewrite the expression every time.

In the Azure portal, we'll go to APIs, we'll go down to named values, and we'll add a new named value. We'll call it time. Now, to get the current time and date, we'll say we'll call it the exact time now. It'll be of type plain, but we could make it a secret if we want it to be encrypted by Azure API Management, and we also could pull from a Key Vault secret if we wanted to. I'll make this plain text. I'll add a C# policy expression to get the exact date and time, and we'll save it.

Now that we have our named value, we can use this time now as a named value throughout our different policies and APIs. Let's go to APIs, basic calculator, with add two integers operation, and we'll open up the code editor. Let's make this easier to see. We'll expand this. Then underneath this other set header, we'll set a new header. Set header. We'll call it exact date time. It'll override if there's an existing header of the same name, and we'll add our named value and save.

Now let's test this, and we should see our exact time and date within the trace. Going to the backend trace, let's jump to the backend, scroll down in the headers, and see here on the bottom our added header with the exact time and date that pulls the exact time and date from our named value.

This should help you get started using named values in Azure API Management. Seeing how these APIs get executed with policy and custom values is great, but what if you had a developer or a friend and team who wants to use an API that's not yet completed? Azure API Management lets you create mock APIs for this use case. Let's take a look at how we can do that.

Before I show you a demo on how you can set up a mock API in your Azure API Management instance, let's talk about what mocking is and why it's beneficial. A lot of organizations manage and organize their development teams differently, sometimes having full-stack engineers that work on both front-end, back-end, and database systems altogether, but also sometimes having teams that are more isolated, where there's front-end teams focused solely on the front-end applications, and back-end teams, and then even database teams. So in this example, when we have front-end teams that interact with backend services, they may make calls to an API Gateway in order to access the backend resources. The issue arises when the front-end team needs to work on their service and the backend service is not complete or even started. In this scenario, the front-end team is blocked. They can't work on their front-end service without the backend service being available. But with mocking, we can set up example responses in our Azure API Management instance for our front-end team to call a mock API and get an example of what the backend service would send to them if it was up and running. This is really easy to do by adding example responses for the API you're mocking and then adding a simple mock response policy so that the front-end team can call the API and not even know or worry about what's going on with the backend service.

Now let's see this work. I'm in the Azure portal, and we'll go to the APIs tab, the APIs page, and we'll make a mock API with our Star Wars API. So closing this, I'll create a new operation. Let's call this get film. It'll be display name get film, name get film, with the endpoint being film. No, we won't add any tags. And then down here for this operation, I'm going to add example responses. So there will be an example for when there's a 200 response. We'll make it application type JSON, and I already have some copied code here from the Azure API Management Hands-On Lab that just has a single film that we'll get back with this mock API. I won't add any headers, and I'll save this.

Now it's important to note, we're not done yet. If I test this API, it's going to call this request URL. Let's see what happens when we hit trace and make the call. We see 404 not found because currently this API doesn't exist. It's still trying to call this backend service with the endpoint API slash film, which is why we want to set up mocking.

To finish setting up mocking, we'll go to design, we'll go to our get film, go to the inbound policies, we'll expand this, and underneath base, open up the show snippets. We'll come down to mock response, add this in, and when we make a request, we want to get the 200 response, so it'll give us the example response for a 200 OK, and the content type will be application JSON. Let's save this, and now we see that mocking is enabled for this particular operation. If I click one of the other operations, I see that mocking is not enabled. It's because we just have the policy on get film. If I test this now, I'll see the 200 OK and our mock response.

This should help you get started with mocking APIs in Azure API Management. Transformation policies and named values may be more common across your APIs, but there might be unique circumstances that require you to send a notification or an event in the middle of an API request response lifecycle. Let's take a look at how you might do this.

Before I show you a demo using webhooks in Azure API Management, let's talk about what webhooks are and why they're beneficial. Imagine I have a bakery business where I may want to inform customers about the new bread, cookies, and brownies that I have. They'll have to give me their information for me to let them know about these things. So I might get a phone number, I might get an email, and I might get a street address, and I can inform these different potential customers about my bread, cookies, and brownies if they give me these things. When a potential customer shares this information, they're essentially hooking themselves into the notification stream that is this bakery sharing information to these potential customers. Similarly, we could have an APIM instance. We could have a backend service or third-party service that's sharing information to any webhook that it's given. There could be different kinds of URLs that are all given to this service as a hook into the notification updates, events, and data that's sent. So when we think about a webhook, it's really just a URL that is being given to some other type of programmatic service so that that programmatic service can send information directly to the webhook. In this way, the webhook hooks into the way in which they can receive information, hence the term webhook.

Webhooks are helpful for several reasons. Asynchronous or one-way requests are helpful when you don't need a response back and you don't want a user waiting for a response over a long period of time. You might have third-party or first-party integrations that you want to set up. You might have push notifications that you want to receive or send out. Automation solutions, logging, and monitoring are also helpful use cases for webhooks.

Now, let's use a webhook in Azure API Management. The way we'll set this up is that we'll have an API consumer send a request to the API Gateway. The API Gateway will forward that request to the backend service. Then the backend service will send the response back to the Gateway, and if the Gateway checks the response and sees that it looks OK, then we'll use a send one-way policy to send a request to that webhook. After that, we'll send the standard response that we got back from our backend service back to the API consumer. We'll take a look at the trace logs to see that the webhook request was sent using the send one-way policy.

We'll use this free online webhook.site to get us a webhook that we can use for testing. We'll use this XML code to add our send one-way policy to our API operation. This is based on code from the Azure API Management Hands-On Lab, and I'll add a link to this GitHub gist in the description.

In the Azure portal, I'll navigate to the API section and the API page. I'll go to the basic calculator API. I'll go to the add to integers operation, and I'll go to the policies to make changes. Close this and expand this to make it a little bit more easy to see. Now coming down to the outbound, after this set header policy, let's add in our code from GitHub. Copy this, put this in here, and then I'll change my URL to be the webhook.site URL. Copy this to my clipboard and add this in. Now I'll save this. I get this warning because in my set body code, I have two at symbols, and Azure API Management wants to make sure that I'm not trying to create policies or expressions using those. The reasons those are there is because this is the format for sending a message card to a Microsoft Teams channel. I'll save this, and now we'll test this. I'll add a value here and a value here, and we'll hit trace in order to look at all of the execution on the policies.

I'll come down to trace, I'll go to outbound, and we can see some of these other policies that executed, and then we see this set body policy. You see my send one-way request policy, and it looks like it was successfully sent to our webhook. Let's take a look at that at webhook.site, and we see it here. So it was successful.

If you want the message card data that we sent to go to an actual Microsoft Teams channel, here's a link to the documentation that I'll put in the description that talks to you about how you can create in Microsoft Teams channels a webhook so that the information can then be sent to that channel. You'll get a URL from this by creating the webhook, and then you'll simply add that webhook as your set URL for this message card.

This should help you get started using webhooks in Azure API Management. All these features that you can add to modify APIs can be really helpful, but only if they're working. So next, let's look at what you can do when you encounter errors in your API Management instance.

There are two types of error handling that we'll go over in Azure API Management. The first is using the return response policy, where we may want to abort the current processing of a single request that's going on to the backend and return a response immediately to the API consumer. The second is by using the on error section in the policies of an API. We will use these two snippets of XML code to demonstrate these two types of error handling. I'll include a link to this GitHub gist in the description.

To implement our return response policy, we'll go to APIs, API page, we'll go to our basic calculator, and then we'll go to divide two integers. Let's add an outbound policy. We'll expand this, and we'll grab our snippet and add it in here. What this is doing is that when we get a status code 500, we'll return a response immediately, and instead of just saying internal server error, we let the user know that the error is on our end. Let's save this.

Now I'll test this. First, I'll just make sure that it works as it should by dividing 4 by two, which should equal two. See response two. That worked. Now let's cause an error. Let's divide by zero. Dividing by zero, I should have an error. I can see my internal server error, but with our custom error messaging, the return response policy can be helpful in certain circumstances where you do need to abort the current processing of a backend service API call, but you want to be careful when you use this because you could fall into the trap of having too much business logic within your Azure API Management instance. It's best practice to let your API Gateway manage policies in the way your APIs are functioning and let the business logic be reserved to your backend services.

Now let's cause an error that will trigger our on error section. I'll grab this XML snippet, which allows us to see information we have in our on error section. It sets a bunch of headers to give us information about the last error property, which is populated when there is an error. Let's save this, and to create an error on purpose, I'm going to create a fake subscription key in the headers. So I'll grab the name of my header for the subscription key. I'll add it as a header, and I'll create just some random characters for the value. This should fail, and I should get a 41 unauthorized response. Creating an error. Oh, I better add a value to actually do this divide, so four divide by two, and then I create a request with a trace where I get the 401 access denied. And because there is an error, I have all of the error information from the headers that we set because of the on error section. We can also take a look at the trace and look at the on error section to see all these headers that are executed in the on error section.

This should help you get started with error handling in Azure API Management. We've covered a lot of ground on how you can add, modify, and troubleshoot an API. Next, let's look at how you can present a new or upgraded API when you have big changes to make.

Versioning in Azure API Management is a way to present new or upgraded APIs in a safe and distinct way. When you use versioning in Azure API Management, you can have multiple versions of the same API with different types of breaking changes. You can specify how API consumers access those versions through different methods like query parameters, headers, or the path, and you can create custom naming conventions that help administrators distinguish versions in the Azure portal and your developers distinguish your versions in the developer portal.

Versioning is not to be confused with revisions. When I worked at Microsoft and spoke with customers about Azure API Management, this was a common mistake that many people made. Versioning is for when you introduce breaking changes, and API consumers can choose when to adopt your new versions using your specified versioning scheme.

Let's introduce versioning to one of our APIs. I'll go over to the APIs page. Let's add versioning to the Star Wars API. I'll hit the three dots and I'll create a new version. This is where I can name my new version and I can decide on my versioning scheme for this API going forward. I'll call this new version V2. I can use a header or query string or a path as my versioning scheme, and I'll choose to use path. My slash V2 is what will be appended to the end of the API in order to show an API consumer that they're using another version. My API version name will be the Star Wars DV2, and I'll add each of these products to this new version. I'll create the new version now.

Coming down, I can now see with this Star Wars API that I have a dropdown for this API, and I have the original version listed and the new V2 version I just created. Even though the original version is listed as original, that name is purely semantic and for organizational purposes. It doesn't change the way the API was working before versions were introduced. If I go to test the Now using the V2 version, I can see that the endpoint that's being called has V2 after my suffix for this API.

In the developer portal, as a logged-in user, I can see these two versions for the Star Wars APIs with a distinguishing factor being the V2 naming convention that I created for this new version. If I click into this, I can also see this additional dropdown that helps me select which type of version I want to use for my Star Wars API, and if I give this a try, I can see that the version that I'll be using is the V2 version here as well.

This should help you get started with versioning in Azure API Management. Presenting new and upgraded APIs is really helpful when you want users to know about the coming breaking changes, but what about standard updates and maintenance to existing APIs? This is what revisions are.

For let's talk about those [Music] next. Revisions in Azure API management are a way to make changes to an existing API in a safe and controlled manner.

When you use revisions with an API, you can make changes without developers ever knowing. You can choose to publish information on your revisions where your developers can see updates and changes via a change log on the developer portal. And it's easy to roll back to older versions of an API if you need to.

Revisions are not to be confused with version name. When I worked at Microsoft, it wasn't uncommon for customers to be confused about what versioning and revisions were. Revisions are meant for when you're making changes to an API that won't introduce breaking changes. API consumers never need to know when those revisions occur, and you can publish them anytime. And you can make changes from new revisions, the default for all API consumers without them knowing. You can also test revisions ahead of time before making them current.

Let's add revisions to one of our APIs. Coming over to APIs, the APIs page, I'll come down to our Star Wars API that has multiple versions, and I want to make a second revision to version number two. I can do this by going to revisions and hitting add revision, or I could go to the three dots and hit add revision. I'll call this my first revision and I'll save it.

In this revisions page, I have two revisions listed. I have my current revision, and I also have the new revision that I just made. I can see that my new revision is online, but it's not current right now. If I want to promote it to be current, I can select these three dots and hit make current.

Before we do that, let's make a change to our new revision. There's also a bar up here to show you the revisions that you're currently on, and I can switch my revisions with this drop down. I'll come over to design and under all operations, under outbound section, I'll set a header. Let's call this header revision, and our value will be the revision number we're on. For us right now, this is revision number two. I'll save this.

And if we make a test and call this, we can see our new header that we just added. Something to point out when you're testing revisions that are not current is that you see this semicolon with this rev equals 2. When you're testing a URL that has a semicolon like this in it, the tools you may be using may struggle to parse the query parameters as part of your API. Keep this in mind depending on the way you're structuring your APIs, because it could make testing revisions a challenge for you.

As a logged-in user on the developer portal, let's test the V2 Star Wars API. Then, as an administrator, we'll promote the second revision to be the current revision, and we'll test the API again. The API consumer won't know the difference, but they will see the new header that we've included in that second revision. So, as a user, we'll make a request, and because we're using the current version, our custom header is not found here.

Back in the Azure portal, let's promote our second revision. I'll come over to the three dots, I'll make this revision current. I will post a change. I'll publish this change so developers can see it. And now, back in the developer portal, first I'll see the change log that exists, and I see the new revision header that was added. And then we'll try this API, and we should see our new custom header. And sure enough, we do.

If something goes wrong with one of your new revisions, you always have the option to roll back to a past revision. I can make this revision number one current and choose to post a change if I wanted to roll back to that old revision. This should help you get started using revisions in Azure API management. We've covered revisions, versions, policies, and more.

Let's conclude with how you can add monitoring and gain insights so you can continuously improve your Azure API management [Music] solution. To start looking at insights in analytics for my Azure API management instance, I can navigate from the overview page down to the monitoring section, and I can see there's three different kinds of analytics and monitoring solutions that we can look at.

The analytics section allows us to see API information, where it was sent, what API requests were made, and more. It does this using the Log Analytics workspaces that are built into Azure. To see information in analytics on many Azure resources, the analytics classic section shows the same information, or at least very similar, but it does this using the old version of analytics which is built into Azure API management. You won't see this classic analytics page if you're using a consumption or V2 version of Azure API management. And at the time of this recording, the analytics classic page is scheduled to sunset on March 2027. If you want to learn more about that, I'll add a link to it in the description.

The last form of monitoring is using Application Insights. Application Insights allows developers to track how API requests are handled all throughout the API lifecycle within Azure API management and their other application solutions.

Let's create a Log Analytics workspace now. Using our naming convention, I'll call it log analytics, it'll be dead environment in the East US for the Hands-On Lab, Azure Innovation Station, and number one. Then we'll review and create this. Create. Our deployment is complete. Now we can go to our resource. Right now, there's nothing connected to this Log Analytics workspace, so I wouldn't expect there to be any information associated with it.

To add my Log Analytics workspace to my Azure API management instance, I can go to the analytics page. I can select collect data from a resource. I'll select my Log Analytics workspace and I'll save this. I already had data in this Log Analytics workspace, which is why I can view it now. But note, if you create a Log Analytics workspace, it may take two to three hours before it can collect data and display it to you in your Azure APM management instance.

When we add Log Analytics workspace to Azure API management, it's added as a diagnostic setting. We can edit the diagnostic setting if we want to change how data is collected by our Log Analytics workspace. In here, we can specify the kind of logs we want to collect. There's only one set of metrics we can collect, which is all or nothing, and we can decide with our diagnostic setting where we want information to be sent. In this example, we have information going to our Log Analytics workspace, and data we collect is specific for our Azure API management instance.

Let's send some requests so that we can start seeing data in our analytics page. I'll come to my basic calculator API, add to integers, and I'll test by sending a couple requests. Now, after a few minutes, I should be able to go to my analytics page and see the data here. I'll filter for the last five minutes and I'll wait until the data displays. I refresh the data, and now I can see my requests that I just made. I can see the timeline of when these requests were made. I can see the geography of where they came from, all in the United States. I can see the specific APIs that I called, which was just my basic calculator API. I can see the operations, the products that were used, subscriptions, and more.

The analytics classic page shows the same information in slightly different formats. If I look at my geography APIs operations, I can see all the same information. This is using the older version of how to view analytics where analytics is stored in your Azure API management instance. Again, note this is being sunset in March of 2027 as of this recording.

Let's create our Application Insights resource. Application Insights and start creating it. I'll use our naming convention for the name. Application Insights does use a Log Analytics workspace to function, and we could use the same Log Analytics workspace that we just created, but I'll create a new one just to keep the data separate. Review and create, and I'll create it. It's done. I can go to the resource, and just like my Log Analytics workspace, there shouldn't be any data here because it's not connected to anything.

And now, let's look at Application Insights. Right now, I can see I don't have an Application Insights resource connected. I'll add one. I'll select our App Insights resource. We created the default login checkbox allows me to collect data on all APIs for my App Insights resource, and the add availability monitor setting lets my App Insights resource check my Azure API management instance to make sure it's available periodically. I'll create this now.

When I go to my APIs, I can go to all APIs and I can select settings and see that Application Insights is configured for all my APIs. Let's understand how these settings work. Application Insights is enabled. My destination is the App Insights resource I created. Sampling helps your Application Insights resource know how many requests it should be collecting at a time. If you collect too many requests, then your Azure APM management instance will not perform as well. Application Insights is meant to do statistical analysis, so we'll only sample about 50% of the requests that are coming through our API Gateway to go to Application Insights. You can learn more about these implications for high API traffic scenarios by going to the documentation.

We want to log all errors that occur to our App Insights resource. We want to log the client IP addresses so we can track where requests are coming from. You have the option to create and add custom metrics if you want to send them to Application Insights. We can choose how much information we want sent to our Application Insights resource, whether we just want errors, basic information, or all the data, which would be the verbose setting. The correlation protocol is to help API requests get tracked end-to-end throughout the whole lifecycle. This is important for distributed systems because a lot of microservices will have requests that bounce around, and it's hard to keep track of where they start and where they end.

By default, Application Insights does not collect the headers or the payload data on API requests, but you can decide to have App Insights collect this data if you choose. We can also get more granular as to the headers and the payload information we want to get sent to our Application Insights resource. When API requests are sent to our API management instance, there's always a front-end request and response, and a backend request and response. We can choose to collect headers or the payload data from any of these specific points in the API lifecycle. I can go into any of these points in the API lifecycle and specify the data I want to collect. I won't do this for now, and I'll save this.

I also have the option to go into specific APIs and change the settings for the Application Insights data collection for that API. The data that's collected for the Application Insights resource on this API overrides the global Application Insights setting that we were just looking at. I'll choose the same instance, and for this API, we will collect all the sampling data. I want this data to be verbose for this API, and I'll save it.

Now, let's send some test requests and then look back at Application Insights to see the data. Go to Application Insights. It might take a few minutes for your data to populate. After a few minutes, we can start to see our data coming through. Some of the other things you can do in Application Insights is look at the application map, which is helpful to see how applications are interacting with each other. We can see our APIM instance, which is interacting with our calculator API's backend, and this will grow when you add more solutions to your Application Insights resource.

We can also view transactions that take place. I can view all the data for the last 24 hours and see a variety of information about each of these requests. Let's look at three of these requests. I can see that Application Insights got a request when a request was made to our API Gateway to do the add calculation for our calculator API. I can see information was also sent to Application Insights when our request was forwarded to the backend calculator API from our API Gateway.

Congratulations! If you've made it through the whole video, you are now equipped with expert knowledge on how to build, manage, and maintain your own Azure API management solution. Let me know in the comments what you liked and what you wish had been different about this masterclass. I take your feedback seriously when it comes to the type of content I create and when I create it. If this video was helpful for you, please like it and subscribe to this channel if you want to see more content like this. Thank you so much and good luck on your Azure API management journey.

Get Our Mobile App

Complete Azure API Management Masterclass! | Beginner to Expert!

Transcription