“10 Things I Hate About Your API” — Amanda Folson
Recapping an excellent PHP[tek] talk on API design
This talk at PHP[tek] caught my eye because it covered more than just code. Amanda Folson is an engineer but also works in Developer Relations, so she’s been a consumer of APIs and a visible representative for her companies’ offerings. She knows this topic from all sides! She spoke in the biggest room at the conference, so I settled in to hear some wisdom. I wasn’t disappointed.
Developer Experience Matters
Her first point was the only one I wish everyone could hear before publishing an API:
Your API is your developer’s experience of your whole product. If the API isn’t good, or if it’s hard to understand how to use it, the developer will use a competitor (or just hate your product).
Developer Experience (DX) is an actual discipline, and one that we can all improve at — and make our APIs more delightful to use when we do. It’s no surprise that DX trailblazers Twilio appeared frequently as positive examples throughout Amanda’s talk. Their team spends a lot of time talking and listening to developers, and trying to smooth out their journeys. Using their products is a pleasure as a result.
A Matter of Perspective
The most important thing with an API, common to all software, is to begin from the perspective of the user. What they are trying to achieve? Amanda made a point that I don’t often hear discussed at conferences: an API is for users to achieve success, not for your company to achieve sales by ticking a box.
I loved her advice to use a pen and paper to work out the structure of your API. It surfaces design issues with how the URLs should work and which fields need to go where — saving you headaches down the road. The talk further highlighted the importance of consistency and of format/validation of fields both as inputs and when returned as outputs. She gave the audience some hilarious examples of similar-but-not-identical field names from an API that she wouldn’t name and shame.
Amanda also recommended pulling in potential users from outside your organisation to try the API and offer feedback. Building a group of alpha/beta testers who can try out their use-cases ensures that you maintain the perspective of the user and properly emphasize their needs in your design.
Keeping Your Product Fresh
Documentation was a key topic of discussion. In particular:
- documentation is not optional
- documentation must be up to date, or you might as well not bother
- documentation includes quickstart posts and tutorials as well as basic API documentation
- documentation should include examples in as many programming languages as possible (personally, I like to include a curl example as an inclusive option)
Again, many of her positive examples featured Twilio, who have turned the tutorial into an art form and have comprehensive tutorials in a choice of languages. I also like how those tutorials are focussed on the outcome the user is intending to achieve rather than the feature of their API that they want to write about. A subtle difference but an important one.
The technical aspects of an API are important. For example Amanda asked us whether we would use an API without SSL in this day and age (plenty are still around). She made some good points about how important it is to load test your API before you release it — and some constructive suggestions about versions, breaking changes, and the use of a change log so that users can know what has changed recently with your product.
Scathing words were said about APIs that return incorrect status codes. It’s vitally important that we build APIs that are standards-compliant, so using status codes and adhering to existing standards for error messages are both great ideas for an API. Pro-tip from Amanda: include links to documentation along with your error messages where appropriate. It’s a great way to help a developer who is having trouble getting something working. It may seem obvious, but more APIs need to follow this approach.
Article.close()
As with all things, the “right” decisions will vary depending what API is being created and what the users’ expectations are. This talk covered some vitally important points that made me reflect on the onboarding experience, not only for APIs but for all kinds of new-to-this-developer technologies.
Thanks, Amanda!
If you enjoyed this article, please ♡ it to recommend it to other Medium readers.
