Lessons After a Decade of API Strategy

After a decade of helping companies build an API platform, here is what I learned that contributes to an effective API platform (in no particular order):

• An API platform requires cross-functional cooperation, not just a focus on API design and delivery. Engineering practices, cloud native practices, product engineering practices, and data management practices all contribute to make your API platform work effectively.
• Many enterprises push their internal services out to partners, but this only serves to frustrate them. Services are for internal composition, not external consumption. Partners don’t want API “LEGO bricks”, they want to experience value delivered through outcomes and inquire about the status of workflows. This requires a different approach to API design than internal decomposition through services.
• It takes more than capable engineers for a successful API platform. Be sure to involve product leaders to make your API platform more effective and that can apply product ownership to their subset of the overall API portfolio.
• Dedicated roles in API governance are the only way to make it happen. A “side of desk” approach is rarely effective in delivering long-term impact, even if it appears to be effective in the short term.
• Establish a clear API platform strategy, then communicate it early and often. Everyone in the enterprise should have a clear understanding of how APIs are involved in daily operations.
• Be sure to define your API platform pillars and policies, then build standards and processes to support them. Without a clear and firm foundation established, day-to-day decisions will slowly erode your API platform effectiveness.
• Obtain executive buy-in and budget, even if it is a smaller budget to start. If you lack executive CIO buy-in, you will always starve for budget and people, and it will always be deprioritized for other urgent items. Enterprises that start bottom-up will always have their initiatives replaced by higher-priority deliverables.
• Industry standards are nice for external interoperability and data portability, but they almost always lack sufficient guidelines for an effective API platform. Embrace, extend, and be prepared to design and deliver your own APIs when needed.
• API platforms are most effective when they align with your business architecture and strategy. This means that enterprises must make an effort to understand and blend their operating model with their APIs.
• Align the enterprise API platform with business objectives through your API strategy, pillars, and standards. Without it, your platform will be less effective as teams lack focus, often going in many directions at once.
• Invest in your API documentation efforts. Get better at producing thoughtful, comprehensive API docs. API documentation reduces frustration, support costs, and can create an barrier to customer/partner churn.

Here are some additional insights for the design and delivery of APIs:

• If using API design first, the delivery effort is reduced and can be optimized as needed through decomposition of the desired API capabilities. Code-first API delivery is useful when there are technical risks that must be identified and mitigations identified. Start code-first, identify risks, then go back to design-first to take an outside-in approach to the API itself.
• Specifications such as OpenAPI, AsyncAPI, JSON Schema, and others must be verified against the implementation or API drift will emerge before the first version is delivered to production.
• Not all developers/engineers have the same experience, so expect to spend time training your staff. Anecdotal evidence is between 25%-90% of your engineers have never seen HTTP over the wire. These are the same folks often assigned to design an API, which results in poor understanding and reinventing the HTTP wheel. This is why we developed API training courses very early on, as the numbers were often higher than today’s average of 25%.
• Federated API coach programs allow enterprises to scale your efforts, especially when resources are limited. You must roll out API design coach training and certifications early to ensure your enterprise is able to spread the experience across teams while you work to upskill teams.
• System analysis and design are the most critical skills for managing an API platform and portfolio. These skills haven’t been taught as much in recent decades, which is the root cause of many failing API platforms.

Anything I missed? Drop me a note or tag me on LinkedIn or X/Twitter.