It can be challenging to establish an initiative to create APIs and microservices within your organisation. But what happens when the initiative catches on and 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 are duplicated by multiple teams in parallel.
Throughout my consulting engagements, I see three key disciplines that contribute to a healthy, managed API and microservice program:
- Be Organised
- Be Consistent
- Be Supportive
Let’s examine each one to better understand what your organisation may be missing or need to improve upon for your API program.
#1: Be organised: Manage your API portfolio
The first and most significant step any company can take to tame their APIs and microservices is to be organised. I have seen companies produce large quantities of APIs and microservices, yet they have no clear organisation of their overall portfolio.
An organisation’s lack of portfolio management results in a spiralling 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:
Partition the 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.
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.
Manage 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.
Properly executed API portfolio management ensures teams across the organisation 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.
You may choose to select a product manager or team to own the API portfolio. Or, seek to introduce a lightweight governance approach as we will discuss next.
#2: Be consistent: Introduce lightweight API governance
A healthy API governance initiative should encourage consistency across the organisation, mixed with the flexibility to support changing market needs. For smaller organisations, or in the early stages of an enterprise API program, a single API architect often fulfils this role. While they may not operate under the title of “API governance” or an “API Centre 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 organisations, API governance may start with an individual but will eventually grow into a small team. Whatever this needs to look like for your organisation, seek to drive consistency across the organisation as the number of APIs and microservices increase.
#3: Be supportive: Make it easy for API adoption
Developers are an essential ingredient of any API program. However, many organisations 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 authorisation 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 initiatives start with good intentions. Over time, however, they can get out of control if left unchecked.
For smaller organisations, having a very lightweight set of coordinating processes and a focus on encouraging API adoption will go a long way. For larger organisations and enterprise IT, it is critical to install a governance team that can help organise 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 organisation transform from a set of adhoc APIs and microservices to a healthy program with a clear roadmap and onboarding process.
