Building and sustaining an enterprise API programme is challenging. From API design standards to increasing API adoption, there is quite a bit to balance effectively. This article offers some tips that can benefit anyone just starting out to those looking for some additional insights for their established API programme.
Tip 1: Focus on business value delivered
Your APIs reflect what you offer as an organisation. APIs need to be reviewed based on where they fit into that offering. Ask the following questions to determine how a new API offers business value:
1. Why are you designing that API?
2. What business goals is it contributing to?
3. What customer pain point does it solve?
4. What are the business drivers necessitating this new API?
5. What are the resources and constraints, e.g. budget, time, and necessary infrastructure?
If you are too focused on the API design before you know what your audience is trying to achieve, your API product will fall short. This is often the case for APIs built on top of a database, as the API simply focuses on data delivery rather than the desired outcomes of what the API can do for the consumer.
API stewardship starts with defining the value proposition and identifying the stakeholders of the API capabilities being designed. Only then can you serve that purpose through it’s design to it’s implementation and adoption by developers.
Tip 2: Do what is right for the API consumer
APIs are the ultimate multiplier for developers, as they can lead to reuse and avoiding the need to write/rewrite code. What one team creates once can be used by many developers and 100s to 1000s or more end users. Yet, time and again I see teams optimising for the API implementation. They make choices to save a few keystrokes or days of development, without considering the impact of those decisions on the API consumer.
An effective API management programme focuses on the API consumer. They advocate for the developers that will integrate the API – even if it demands a bit more work by the API implementation team. This includes the need for great API documentation, test coverage, and a thoughtful API design.
Tip 3: Establish an API style guide early
Establish a style guide with naming patterns and other key design decisions captured. This will provide the necessary checklist that will help design reviews produce consistent API designs. This is especially important as the number of teams producing APIs grows.
Without a style guide in place, teams will be forced to decide how their API should look. From naming standards to common design patterns. Not only is this burdensome for the producing teams, it can be frustrating for developers forced to adapt to different API design styles as they integrate across APIs in your portfolio.
Tip 4: Centralise governance early, federate as needed
For those that went through the age of SOA, the thought of governance probably brings back mixed or negative emotions. Many organisations have learned from those mistakes, shifting their focus of governance from internal optimisation to a focus on the external developer experience.
A healthy API governance initiative should encourage consistency across the organisation, mixed with the flexibility to support changing market needs. In the early stages of an enterprise API programme, a small group of API architects will often fulfill 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.
Effective governance focuses on coaching over caustic feedback. They seek to empower teams to be self-governing as much as possible. They drive consistency and seek to cross-communicate the experiences of other teams. All while integrating into an agile process.
For larger organisations, adopting a centralised approach helps to establish the baseline set of standards. Over time, some are finding that it is more efficient to federate some of the processes to trained representatives that can conduct design reviews on behalf of the central group.
Tip 5: Get control of your API portfolio
I have seen companies produce large quantities of APIs and microservices, yet they have no process for organising their API surface area. An organisation’s portfolio of APIs is a digital reflection of their capabilities and day-to-day business practices. An organisation’s lack of portfolio management results in a spiralling effect, where new APIs are built independently and often with overlapping functionality.
Effective API portfolio management ensures teams across the organisation can contribute to the overall portfolio, rather just a select few individuals or teams.
Tip 6: Optimise for adoption
Many organisations focus on the strategy and processes to create APIs but forget to address the need to support easy API adoption. This includes an uncompromising focus on thorough documentation, a simple onboarding process, and assistance with making their first successful API request.
Focusing on the wrong problem results in delivering an API product that fails to resonate with the target audience and therefore gain wide adoption. If you don’t validate your assumptions as you go along, then you’ll end up building the wrong thing for the wrong audience.
Focusing on API adoption helps to build awareness of available APIs, while avoiding the development of APIs that are rarely (or never) used by developers.
Tip 7: Not all APIs will be designed top-down
Many organisations begin their API programme through the introduction of APIs that power their mobile or web apps. These APIs are typically built out of necessity rather than intentionally using a top-down, API design first approach. Over time, these organisations shift to a top-down approach and may even become strict about this approach.
Not all APIs that your business offers will be designed top-down. Limited time is often the leading factor. However, I’ve seen some powerful APIs start with a developer’s idea and grow into something amazing. As many developers know, sometimes you just need to put code toward an idea and see where it takes you.
That said, APIs built bottom-up will eventually need to have their design and documentation reviewed. Be willing to accept APIs designed with a different process – as long as the developers understand that they may need to re-write some of their API to be compliant with the organisation’s standards.
Bonus: Don’t forget to include events and data streams
Most APIs are thought of as request-response over HTTP. We are now seeing a renewed interest in event-based APIS over HTTP. From the popularity of webhooks to connect SaaS solutions, to the introduction of technologies such as Kafka to drive internal messaging, our API portfolio is moving beyond REST.
API eventing completely changes the way API consumers interact with our APIs, creating new possibilities that request-response cannot. They are driving innovation and extensibility of enterprise platforms, empower developers and users to collaborate in new ways, and will begin to open up the opportunity for low-code/no-code tooling.
Likewise, data streaming through technologies such as Apache Kafka and Apache Pulsar are becoming popular for operationalising your data lake and warehouse. They operate at a scale that exceeds traditional message brokers.
AsyncAPI is a specification for capturing your events and streaming message details. Like OpenAPI Specification and API Blueprint, it is machine readable and can drive documentation, code generation, and development processes. The specification works with traditional message brokers, HTTP streaming, message streaming via Kafka/Pulsar, and even IoT with protocols such as MQTT.
As you start to take ownership of your enterprise platform, don’t forget to include web eventing, data streaming, and your internal messaging as part of your API programme.
Wrap-up
Establishing and maturing an enterprise API programme requires the proper mixture of processes, approaches, and coaching. Don’t let it overwhelm you. Anyone in the same position will quickly acknowledge that it all doesn’t start at day one. Start simple, expand the programme over time, and be willing to make adjustments as necessary to fit the needs of the developers you represent.
Want to learn more on best practice tips for tackling your API Strategy? Then you’ll want a read of our free whitepaper “Approaching Your API Strategy“. It’s 32 pages full of practical tips and case studies for taking yours from start to finish.
