Why Your New API Product Will Fail

by Scott Feinberg

In this talk titled 'Why Your API Product Will Fail,' Scott Feinberg discusses the key elements necessary for developing successful API products that resonate with developers. He emphasizes that despite having well-designed APIs, many still fail to gain traction due to poor usability and inadequate documentation. Feinberg aims to illustrate how well-constructed API tooling can prevent these failures and enhance user experience.

Key points include:
- Importance of API Tooling: Effective API tooling consists primarily of clear documentation and reactive API clients, enabling users to make the most of the API.
- Value of Tutorials: Tutorials should provide straightforward, step-by-step instructions for using the API, catering to users at all skill levels, and minimizing excessive text. Tutorials should include explanations, use cases, and structures that facilitate easy implementation.
- Reference Documentation: Developers rely on thorough reference documentation that clearly details functions, API calls, parameters, and expected responses. It should be crafted to allow users to navigate without confusion, supported by clear examples, particularly in JSON format.
- Maintaining Consistency: Ensuring detailed specification, such as through JSON schema, Swagger, or RAML, is crucial for keeping documentation up-to-date and consistent over time. This combats confusion that arises from misaligned documentation and product features.
- Significance of Documentation: The quality of API documentation is equal to the quality of the API itself. If users find the instructions inadequate or unclear, they are likely to abandon the product. Investing in robust documentation tools will enhance user confidence and engagement.

In conclusion, adhering to best practices in API documentation and tooling is vital for creating API products that developers will enjoy using. Clear, up-to-date instructions and intuitive tutorials can significantly improve the user experience, ultimately leading to the success of an API product.

00:00:11.679 Thank you all for making the mistake of coming to my talk. I really appreciate it. So, my name is Scott, and I work for a company that specializes in API-based payments, similar to Stripe. We provide payment solutions for companies like Constant Contact.

00:00:36.559 My talk is titled 'Why Your API Product Will Fail.' If you're looking to attract an audience to your talk, having a clickbaity title is crucial, and that's what this title aims to be. An even better title might be something along the lines of 'How to Build API Products That Don’t Disappoint.' Some people confuse me with Taylor Swift, and I was told that if I included a photo of her, people would be nicer to me.

00:01:18.799 Today's agenda will cover what good API tooling looks like and how to build it in a scalable way. How can I design something that won’t make me panic every time I launch a new version of my API? Let's start with understanding what API tooling is.

00:01:40.960 Before we dive in, how many of you have ever used an API before? Most of you, great! Now, how many of you have used an API that was poorly designed? A lot of people, I see. And how many have used an API that did not function as documented?

00:02:01.520 Ideally, well-constructed API tooling prevents these issues from occurring. The purpose is to give us, as developers, a chance to use the API exactly how it was intended to be used. Remember that every time you interact with an API, there was a developer, perhaps someone in this room, who wrote the documentation or created the actual API.

00:02:27.440 API tooling consists mainly of two components: documentation and reactive API clients, which some people refer to as SDKs or wrappers. These are the essential ways users interact with your API. Most services provide documentation that includes tutorials, reference docs, and explanations of use cases.

00:03:00.159 Let's start with tutorials. How many of you have, when starting with a new API, jumped directly into the reference docs? Probably not many. Instead, you likely sought out the smallest action you could take with the API and looked for a how-to guide. A good tutorial needs to clearly outline what you're doing, especially if you've never used the API before. It should provide detailed steps that even a junior developer on your team can follow.

00:03:51.519 Here’s an example of what a tutorial should look like: it should start with an explanation of what you're doing, have an example use case, and provide a high-level overview of the steps involved. Often, tutorials are too text-heavy—don’t make me read too much. Make it easy for me to follow along and copy-paste necessary code without excessive searching.

00:05:00.560 Following tutorials, you will likely need to utilize reference documentation, which details all the API calls and their functions. It’s critical to provide clear examples of API calls and their parameters. Documenting expected responses, including JSON examples, enhances the user experience significantly. Users want to feel comfortable navigating your API without having to rely on understanding complexities they may not be aware of.

00:06:54.560 Your reference documentation must be thorough, simplifying the process for users by providing clear descriptions of what each parameter does and how it should be used. Don't just rely on users making API calls to learn the mechanism—be proactive in providing clarity.

00:08:08.600 Moreover, it’s vital to maintain up-to-date specifications of what your API does. Without having a single source of truth, updates and documentation can become inconsistent, leading to confusion. Using a spec like JSON schema, Swagger, or RAML can help maintain this clarity by allowing you to document your API comprehensively.

00:10:51.200 While creating documentation, the spec should be implemented in a way that allows ease of updates and refers to a set template. My advice is to document clearly, ensuring people can easily understand how to use your API and the common errors they might encounter.

00:13:33.600 In the end, remember that your documentation is as important as the product itself. If people are consuming your API, they need to feel confident using it. Investing in building robust tools for documentation is crucial, and recognizing its value can prevent potential drop-offs in users because of poor instructions.

00:20:25.120 Thank you for your time, and I hope you gained some insights into building effective API documentation that enhances user experience.

00:21:01.919 Are there any questions? I would love to hear your thoughts or concerns regarding API documentation or tooling—please feel free to share.