Podcast #15 - James Higginbotham - LaunchAny

The conversation between James and Sid covered many important aspects of API design and management. James has over 20 years of experience as a consultant, helping enterprises and startups design great APIs. He shared his insights on best practices for API design, documentation, dealing with API sprawl, and retiring APIs.

A key topic they discussed was the importance of high-quality documentation for APIs. James explained that documentation should not just be an afterthought, but it should be a core part of the API design process from the beginning. Good documentation focuses on the outside perspective of API consumers and their use cases rather than the internal implementation details. Scenarios and examples are critical for enabling developers to understand how to use the API properly. Documentation is one of James' five core principles of API design, along with not designing in isolation, focusing on outcomes, picking design elements that match needs, and planning for APIs to last over time.

Related to documentation is the role of SDKs and helper libraries in making APIs easier to use. James and Sid talked about different models for where these SDKs and libraries originate. Often, the API provider releases official SDKs to abstract away complexity and make common tasks simpler for developers. But SDKs and libraries may also come from the community through open source projects, or be built by API consumers themselves based on the API definitions and documentation. Well-designed APIs enable these SDKs and helpers to be created organically.

When dealing with API sprawl from acquisitions or multiple internal teams, James recommends strategies like mapping processes and capabilities to existing APIs first before creating new ones. Legacy APIs can be leveraged by creating a unified front-door API that abstracts the implementation behind a consistent and well-documented facade. The emphasis should be on understanding the problem to be solved and jobs the API needs to enable, rather than just exposing existing implementations.

For retiring APIs, James stresses analyzing business needs and carefully transitioning existing consumers in a step-by-step manner. APIs often last for a very long time, so a solid process for deprecation and sunsetting needs to be planned upfront.

Overall, James provides excellent advice for organizations looking to improve their API design practices. His principles align with industry best practices around focusing on outcomes, understanding API consumers, investing heavily in documentation, and planning for change over time. High-quality documentation, SDKs, and helper libraries are key enablers for API adoption. By following James' recommendations, companies can create APIs that better meet their business goals and developer needs.

The full conversation contained many more insights around API design best practices. James emphasized the importance of not designing APIs in isolation, but rather taking a user-centric approach focused on empathy, discovery and outcomes. He advocates picking design elements like protocols and data formats that match the specific use case rather than defaulting to trends. His advice can help organizations avoid common pitfalls and create great developer experiences with their APIs.