Assume you joined an organization today that produces hundreds of independently deployed & hosted APIs and you now carry the responsibility of managing all these APIs from different teams across the entire organization. This can be a lot of work, right?
What if I told you there is a way to streamline API development and governance through centralization of APIs and simplify your experience enforcing design patterns across all development teams in your organization. In this blog, you will get to experience first hand the responsibilities of an API Platform team in an organization. Buckle up and prepare for action!
To get the most out of this blog, I advice you to open 2 separate tabs to;-
- follow along with this blog
- open the referred unit for practical steps
Imagine this, you have just joined Contoso Corporation as an API Platform Engineer, and after joining the organization, you discover the following issues: -
- There are different teams operating independently, with each producing their own set of APIs.
- These different teams are using different API design philosophies leading to inconsistent API design across the organization.
- There are duplicate APIs because these different teams have no organization to know which APIs currently exist within the organization
- Some APIs are ungoverned and not maintained, leading to potential security threats
You biggest responsibility in your role is to streamline API development and governance to ensure best practices are being implemented across all these teams. Your key stakeholders are API producers, API Consumers the API Platform Team. Read more about the roles and responsibilities of each of these teams.
Luckily, you already know of the perfect tool to help you achieve this level of API organization and governance within your organization. Azure API Center. Now, let's get to work.
Create an API Inventory
First, you want all APIs produced in the organization to be consolidated in one centralized location. You can choose either to add all APIs personally or have representatives from the individual teams register their APIs into your organization’s API Center. Learn to register APIs through the Azure portal or Azure CLI to API Center at step 3.
To sort, arrange and easily navigate these APIs, you define mandatory API metadata that will be required for every API that will be registered in your API Center.
Example, for Contoso, it is now a requirement that all APIs, regardless of the team producing it, to assign an API Approver who will be single point of contact for all matters regarding the API. All APIs must also have a status property to show whether the API has gone through the mandatory compliance review or not.
These properties and more will allow you to easily sort and filter through the API inventory. Learn to define metadata properties for APIs within the organization at step 2
Enable Linting and Analysis for API Governance
Second, every team producing APIs needs to design and develop APIs following your organization’s API style rules. To improve the development experience and avoid a lot of back and forth after reviews, you onboard all developers to using API Center’s extension for VS Code to apply linting that will detect common errors and any inconsistencies that don’t conform to your organization’s API style rules. Read on how to define and implement your API style rules
Early Detection of Breaking changes
In your investigation, you also noticed that some API versions introduced breaking changes after release to API consumers and you want to avoid this for future iterations. For this, API producers in your organization use the ‘Detect Breaking Change’ feature in the API Center VS Code extension, to discover versions with breaking changes early enough before they are rolled out. Read on how to detect breaking changes in VS Code
API Discovery & Consumption
Before any team begins the development of a new API, you want them to have an easy way of discovering the available APIs in the organization.
- You recommend that all developers use the API Center VS Code extension to quickly perform a search to see all registered APIs in the organization.
- To expose all APIs to both API producers (internal) and API consumers (external), you also deploy a self-hosted portal website for all APIs. Read on how to set up the API Center portal here
3. To help API consumers easily integrate these APIs into their applications with no complexities and without manually writing HTTP requests, you onboard them to use API Center to generate SDK clients for selected endpoints with their preferred programming language. Read on how to generate and API Client using API Center.
Now, Contoso has a centralized API inventory to track all APIs regardless of their development team, type, lifecycle and deployment location. This simplifies the development, governance, discoverability and consumption of all organizational APIs. Complete the Introduction to API Center module on Microsoft Learn to earn a badge after completing the Contoso scenario.