OK, if the Bill & Ted reference didn’t do it, you should know the Azure API Management is a very powerful service for your APIs. This SaaS solution allows you to easily manage thousands of APIs, control access, define subscriptions and limits, all from the comfort of your couch (because it’s 2020 and that’s where everything happens now). What’s even better, is the entire service is nearly maintenance free, allowing you to focus on your code.
Learn more about Azure API Management Services.
If you’re like most developers, you have a bunch of existing APIs that you will need to work with. Importing these solutions into APIM is the key to unlocking the management features of the platform. So, you have a bunch of APIs and OpenAPI specifications for them. But how do you get them into APIM? Let me show you.
Before we get to importing, we need something to work with. I create a simple API with a few methods to GetAPic and PostAMessage.
Here’s the VS project.
I deploy the code to an Azure App Service for hosting.
And here is a sample Postman request to the API. (Calvin & Hobbes FTW!)
With the API created and deployed, I’m ready to create an OpenAPI definition. There are several ways to do this, including creating a definition as part of the API design process. In my case, I want to show how this can done after an API is already deployed.
The Swagger Inspector tool allows you to create a definition for an existing API by documenting the requests you send to the site. Using the tool, you can specify the type of request, body, and other attributes. Swagger Inspector logs the details and allows to you select the methods you want to include in your definition.
In Swagger Inspector, I log a request for my GetAPic and PostAMessage methods.
Learn more about Swagger Inspector.
Once the definition is created, I view the details within SwaggerHub. This portal allows me to review the definition, updates descriptions/titles, and format and export my definition file.
Here is my definition in SwaggerHub with my 2 methods defined. Note the server url value is for my Azure App Service.
Learn more about SwaggerHub.
When importing an API into API Management, you can take a few different routes. You can import via a URL or file, depending on your needs. In my case, I want to use a definition file. Within SwaggerHub, I choose the Export option and download the file.
With the definition file downloaded, I’m ready to import. In my Azure APIM service, I choose Add API and select the OpenAPI option.
As you can see, APIM offers several options for importing your APIs. You can use a variety of definition file types, as well as start from a blank API. If your hosting your code within Azure (App Service, Function App, Logic App), the process is even more streamlined.
On the Create from OpenAPI Specification screen, I select my definition file. The utility reads the details and populates the form.
Be sure to set the API URL suffix to your desired API path.
Once the API is imported, I can view the settings and verify everything is correct.
APIM services work by defining Products and Subscriptions. Be sure to set the Products that apply to your imported API.
With the API imported, I do some tests to confirm everything is working properly. Within the APIM portal, I can quickly test any API methods I have exposed.
I select the GetAPic method and click Test.
Here is the result of the method call.
Next, I select the PostAMessage method and provide a sample body.
And, here is the result.
Lastly, I open the Developer Portal to confirm the new API is available for my users. Because I selected the Starter and Unlimited products, the API displays for my users.
With my new API imported, users can now access the functionality and start using my service.
The Azure APIM portal provides everything a developer needs to import and configure an API. If GUI’s aren’t your thing, the Azure APIM PowerShell commands allow you to do everything via code, as well.
Here’s the same import process, completed using the Import-AzApiManagementApi command.
$ApiMgmtContext = New-AzApiManagementContext -ResourceGroupName "bsoltisapimdemo-rg" -ServiceName "bsoltisapimdemo-apim"
Import-AzApiManagementApi -Context $ApiMgmtContext -SpecificationFormat "OpenApi" -SpecificationPath "C:\Users\XXXXXX\Downloads\bryansoltis-ms-BSoltisDemoAPI-0.1-swagger.yaml" -Path "bsoltisdemoapi"
I execute the command in PowerShell.
The API is imported and can be configured / tested, just as if it were done using the portal.
Check out the Azure APIM PowerShell commands.
OpenAPI is a leading industry standard when it comes documenting and defining APIs. By leveraging Azure API Management for administration, developers can quickly import their applications and manage their systems on a global level. Through the Azure portal or code, you can get your APIs into a managed environment and help your users develop their applications. And maybe just help out Bill & Ted along the way! Good luck!