Creating an Effective API Program
It can be challenging to establish a healthy API program within your organization. But what happens when your teams start to produce a large number of APIs and microservices? Things can get out of hand quickly, resulting in APIs that go unused or rebuilt multiple times.
Effective API programs require three key ingredients:
- API portfolio ownership that meets the needs of both internal and external stakeholders,
- Lightweight governance that combines coaching with consistency, and
- Ease of API adoption for increased speed and efficiency.
Let’s examine each one to better understand what your organization may be missing or need to improve upon for your API program.
1. API Portfolio Ownership
The first and most significant step any company can take to tame their APIs and microservices is to be organized. I have seen companies produce large quantities of APIs and microservices, yet they have no clear organization of their overall portfolio.
An organization’s lack of portfolio management results in a spiraling effect, where new APIs are built without knowledge of others that already exist. Plus, it isn’t always clear who should be responsible for a new API - your team or someone else. It doesn’t take long for this spiral effect to render an API program messy and ultimately labeled by executives as a failure.
As your API program expands, seek to tame your portfolio of API and microservices through the following steps:
Manage your API portfolio: Not all APIs are related (e.g., customer accounts, orders, and inventory for an eCommerce platform). Separate your APIs and microservices into domain areas and assign product ownership of each area. Select a product manager to own the entire API portfolio, or place it under the stewardship of an API governance team.
Craft a clear process to add new APIs and microservices: By defining a clear process for adding new APIs into the portfolio, API consumers will have an easier time finding the APIs they need. Properly executed API portfolio management ensures teams across the organization can contribute to the overall portfolio. It will also make the job of consuming teams easier when looking for an API to address the needs of their apps.
Oversee URL paths: The URL paths under your API domain name (e.g., api.mycompany.com/accounts) are like real estate for developers. Manage your URL paths through the use of prefixes or other naming conventions. This will scope resources to domain areas to prevent scattered API endpoints, duplicate or confusing resource names, and conflicting paths.
2. Introduce Lightweight API Governance
A healthy API governance initiative should encourage consistency across the organization, mixed with the flexibility to support changing market needs. For smaller organizations, or in the early stages of an enterprise API program, a single API architect often fulfills this role. While they may not operate under the title of “API governance” or an “API Center of Excellence”, they are often performing the duties of a governance team:
- Coaching teams on API design techniques
- Delivering educational material, training, and other resources to communicate shared knowledge
- Empowering solution teams to discover and consume existing APIs
- Defining clear API standards, protocols, and design patterns supported through an API style guide
- Creating policies for onboarding, rate limiting, and access control
For some organizations, API governance may start with an individual but will eventually grow into a small team. For larger organizations, it may evolve into a federated governance model. Whatever this needs to look like for your organization, seek to drive consistency across the organization as the number of APIs and microservices increase.
3. Make API Adoption Easy
Developers are an essential ingredient of any API program. However, many organizations focus on the strategy and processes to create APIs but fail to address the need to support easy API adoption.
Common tasks to drive increased API adoption include:
Maintain great documentation: Your documentation is the first encounter most developers will have with your APIs. Provide great documentation to drive awareness and understanding. This should include a focus on: what your API offers, how to use it, and what to do when they are ready to start integrating.
Help developers get started quickly: Developers who are new to your API do not have an easy journey. They must learn what capabilities are offered, determine if they solve the problem at hand, and how to get started using your API for the first time. Make it easy for developers to get started through this journey through quick start guides and case studies.
Define a clear onboarding process: Think beyond reference documentation by offering a complete developer portal that guides integrators through the onboarding process. This includes an introduction to the API’s authorization approach, the capabilities addressed, how to onboard in a sandbox environment, and how to gain access to production.
Focusing on API adoption helps to build awareness of available APIs. It also prevents wasting time and resources to construct APIs that are rarely (or never) used by developers.
Wrap-up
All API programs start with good intentions. Over time, however, they can get out of control if left unchecked. For smaller organizations, having a very lightweight set of coordinating processes and a focus on encouraging API adoption will go a long way. For enterprise IT, it is critical to install a governance team that can help organize your API program, drive consistency, and help grow API integrations.
While it may be challenging at times to launch and sustain an API program, it is ultimately rewarding as you see your organization transform from a set of adhoc APIs and microservices to a healthy program with a clear roadmap and onboarding process.