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.
