Your company provides a lot of APIs to both external and internal consumers. Your API landscape is every API you’ve built, plus those in the early stages of design and development. Before you can make decisions within this landscape—such as which APIs are working well, which may need to be shelved, and which may need to be beefed up—you need to identify them and how you’ll make decisions. A deep dive into your APIs and their governance is a big project. As you’ll see, it doesn’t have to happen all at once, and there are some useful ways to categorize your APIs that might structure your approach.
Don’t Start With Everything
Rome wasn’t built in a day and you can’t boil the ocean. These may be business clichés, but they’re important to your API landscape. Accept that you won’t have a handle on the entirety of the landscape right away. Yes, you want to be methodical and detail-oriented, but you also want to be realistic. Incremental improvement of your API landscape should be the goal.
As with anything in technology, change is inevitable. After all, even if you could take a snapshot of today’s landscape, that would be different tomorrow. Your organization is building new APIs to support new initiatives. You’re not only cataloging what is available today, but how you will identify new functionality in the future.
Since you aren’t starting with everything, you need some method to determine where to focus. In some organizations it could make sense to review by departments or product lines. The next two sections will give two different ideas for categorizing your APIs.
Identify API Varieties
One helpful lens to your organization’s API landscape is looking at the variety within your APIs. Among the biggest differences between APIs are the protocols or architectural styles they use.
For example, you may have combinations of APIs using the following styles:
- REST (REpresentational State Transfer)
- RPC (Remote Procedure Call)
- SOAP (Simple Object Access Protocol)
- gRPC (HTTP/2 RPC developed by Google)
While this step alone might not narrow your choices, it will inform what additional information you’ll need to provide a complete view of the landscape.
Identify Lifestyle Stage
In addition to varieties, you can consider whether an API is in production, development, or at a different lifestyle stage. For example, it might be easiest to first look at APIs still in the design phase, so you can determine how to have maximum impact on the landscape. Or, look first at production APIs, so you can determine redundancies. The following are some commonly used stages:
- Planning: Documentation of specific needs of the API. Planning should always include how you will track the API, what security components it will utilize, and possible performance issues you could come across.
- Development: These APIs are in the process of being built by your team of engineers.
- Testing: These APIs are in the process of being tested. You should have your API be tested in three different routes, functional, performance, and acceptance testing.
- Deployment: These are active API that is being monitored and used by your organization.
- Retirement: APIs that are no longer in use.
You can make these stages more granular (such as separating strategy and design) or as simple as pre-release vs release. The key is to use a stage, optionally alongside other categorization, to help you identify the most important APIs within your entire landscape.
When you identify the API landscape of your organization, you give yourself the information required to tackle other API projects. You can’t implement an API governance pattern, for example, without some knowledge about your landscape’s stage and variety. While you can’t do it all at once, you can start today, and lay the foundation for your organization’s API future.