In today's fast-paced world of software development, a well-designed developer portal is crucial for fostering innovation, improving developer experience, and streamlining API integration. A developer portal serves as a centralized hub where developers can access essential resources, documentation, and tools to effectively work with your APIs and services. In this article, we will specifically focus on Azure API Management (APIM) as our backend service

By implementing a developer portal, you can:

1. Enhance developer productivity by providing clear, comprehensive documentation

2. Facilitate API discovery and adoption

3. Build a community around your products

4. Gather valuable insights and feedback from users

5. Showcase your APIs and resources to a broader audience

You may already be asking yourself “Doesn’t Azure provide a Developer Portal automatically for my Azure Products and APIs?”. The short answer is yes. While the native Azure Developer Portal is a great option for covering basic use cases for small Product offerings, more robust API initiatives and Product suites may require more control to customize for features such as:

1. Advanced Search capabilities

2. Translation and Internalization

3. Filtration options on Product Catalog

4. Alternative layouts, displays or metadata for Product and API Specification 

Additionally, the vast amount of functionality provided by the WP Plugin ecosystem and overall simplicity of WordPress can make it an easy contender for your Developer Portal.

Customizing Your Azure Developer Portal

The goal of this tutorial is to walk you through the process of creating a WordPress-based Developer Portal using the Azure API Gateway as the backend. A core dependency will be the Azure WP Plugin which is developed and maintained by Microsoft. This powerful combination allows you to leverage the flexibility of WordPress with the robustness of Azure's cloud infrastructure, resulting in a scalable and feature-rich developer portal.

We will be making the assumption in this article that you have already setup and configured your Azure APIM and created Azure Products and APIs. If you haven’t, Microsoft has great documentation on how to do this.

We'll cover the following steps:

1. Installing WordPress on Azure <anchor to section 1>

2. Setting up an Azure Repository and connecting CI/CD <anchor to section 2>

3. Downloading and customizing the WordPress Plugin <anchor to section 3>

4. Overview and Customization of Azure APIM WordPress Plugin <anchor to section 4>

By the end of this guide, you'll have a fully functional developer portal that will serve as a valuable resource for your API consumers, fostering better developer experiences and driving the success of your API ecosystem.

Let's dive in and start building your WordPress Developer Portal on Azure!

Installing WordPress on Azure

To begin setting up your WordPress Developer Portal on Azure, follow these steps:

1. Log in to your Azure portal (portal.azure.com)

2. In the search bar, enter “App Services” and select App Services under the Services section.

   

3. Click the Create caret dropdown and select "WordPress on App Service"

   

4. Fill in the required details:

   1. Subscription: Choose your Azure subscription

   2. Resource group: Create a new one or select an existing group

   3. Region: Select the closest data center to your target audience

   4. Name: Choose a unique name for your WordPress site

   5. Operating System: Select "Windows" or "Linux" based on your preference

   6. App Service plan: Create a new plan or select an existing one

   7. Click "Review + create" and then "Create" to deploy your WordPress site.

   8. After your WordPress installation has completed, you’ll want to add a plugin to easily export your DB (and files) from your remote WordPress site to set up locally. We used WP Migrate DB for the sake of this article, however feel free to use whichever you prefer. 

Once the deployment is complete, you can access your new WordPress site using the URL provided in the Azure portal.

If you run into any issues, please consult the official documentation for installing WordPress on Azure to complete this step.

Setting up Azure Repository and CI/CD

To enable continuous integration and deployment for your WordPress site, you’ll first need to set up a repository in GitHub (or Azure). Given the robust amount of resources for setting up a repo, we’ll exclude those steps from this tutorial. Once your repository has been created, you can follow these steps to connect it to Azure:

1. In the Azure portal, navigate to your WordPress App Service

2. Under the "Deployment" section, click on "Deployment Center"

3. Choose "GitHub" as your source control

4. Connect your GitHub account and select the repository you want to use

5. Configure your build provider (Azure Pipelines or Kudu)

6. Review and finish the setup.

Azure will now automatically deploy changes from your GitHub repository to your WordPress site.

Downloading and Customizing the WordPress Plugin

To enhance your developer portal with Azure-specific features, you’ll first want to setup a local environment to develop against. DDEV is our local web development tool of choice for standing up local environments quickly in WordPress.

1. Download the APIM Devportal plugin from GitHub

2. Move APIM Devportal plugin to /wp-content/plugins

3. Navigate to the WordPress admin panel of your site

4. Click "Install" and then "Activate"

5. In the WP Admin Menu, click “Azure API Management Developer Portal” to connect your plugin to your Azure Developer Instance:

   1. APIM Service Name can be found by navigating to the Overview section of the Azure API Service in Azure Portal -> Developer Portal URL.

Check both “Create Default Pages” and “Create navigation menu” to allow the Plugin to generate defaults for you.

6. Voila! Your environment is now connected to your Azure Developer Portal!

Now that we have our Azure API Management service, our CI/CD service connected to our repository and our local installation of WordPress running with the Azure APIM plugin, let’s dig into the fun stuff! 

Overview of Azure APIM WordPress Architecture

Before we dig into changing the code in the plugin itself, we’d like to do a quick overview of technologies used in the plugin itself.

1. For the UI, the plugin uses React to render the components.

2. For injecting the components themselves into WordPress pages, the plugin uses Shortcodes.

A familiarity with both React and WordPress itself (and PHP of course) will be required to add any advanced customizations or alterations to the existing plugin. If you are not familiar with either of these OR you’d like to outsource the work, Achieve has a team of experts on standby ready to assist you with any of your needs.

Steps to Customize the Plugin:

1. Open the plugin files for the Project in your favorite IDE. For customizations to the plugin itself, you’ll be working in /wp-content/plugins/apim-devportal specifically.

2. Adjust layouts and/or displays of the React components, inject additional metadata into the Shortcodes to access in the React components or do other necessary changes to adapt the plugin to your specific needs

3. Test your changes locally before pushing to GitHub.

4. After pushing your changes to GitHub, CI/CD will trigger and deploy your changes to your remote WordPress environment.

5. Test on your remote environment.

For more advanced features, customization or for a complete Azure API Management product offering, please contact our sales team for more information on how we can help supercharge your Developer Portal experience!

Conclusion

As API and API Developer Portal specialist, at Achieve Internet we recommend you remember to regularly update your documentation, API references, and other resources to keep your developer portal valuable and up-to-date.

By following these steps, you've created a powerful WordPress-based developer portal using  Azure APIM. This platform will serve as a crucial resource for your API consumers, improving their experience and driving the success of your API ecosystem. As your API Suite grows, continue to gather feedback from your users and iterate on your portal to ensure it meets the evolving needs of your developer community.