The future of APIs is (still) beginners
by Taylor Barnett-Torabi
In a talk in 2019, I said, “Beginners' struggles are all our struggles.” Now, five years later, I still find this completely true. The future of APIs is (still) beginners.
This blog post is inspired by API Futures, a creator-led initiative that brings together a diverse array of voices from across the API community. Each participant shares what they believe is the most significant opportunity or challenge in 2024 (and beyond). Think of it like webring for folks who want to talk about the future of APIs. You can see other blog posts and videos on the API Futures page. I'll be adding some more folks posts throughout the post.
In this blog post, I want to explore what really is beginner, why it is important to center around beginners in API work, and some examples and lessons based on real experiences in some of my API developer experience work.
What is a beginner?
Before I get into the "why," I want to clearly define what I believe a "beginner" is. Historically, I found the term "beginner" in software development to mean "someone who is new to software development." In the case of APIs, someone is just using APIs for the first time. I'd like to throw that definition into the trash. 🚮 Instead, I want to use this definition: A beginner is someone new to anything. It could be a specific API, tool, framework, or literally anything -- even something as small as a feature!
This definition of beginners is not only more inclusive and brings more folks into our tent of beginners, but it also allows us to view APIs through a new lens, even for experienced developers.
For example, both a first-year developer and an experienced developer can have the same struggles with an API if the API design is not well thought out. It is an everyone problem.
So, why is the future of APIs beginners?
When you treat your audience as beginners, it makes the API better. You are forced to think through your models, your endpoint naming conventions, your authentication methods, your whole getting started experience, how different endpoints interact, and so much more. You can't just yeet it out there and think, "Developers will know what to do."
This may seem obvious to some, but I think many API producers still struggle with it. And it is only becoming more important.
Every minute that a developer spends on a confusing API that is supposed to solve an undifferentiated software problem for them is a minute they could have been focusing on their core business goals. And, like, actually building a product! (I think most of us like salaries, right?) We've come to rely on APIs for so much. We don't have time to waste on them.
If something is fairly intuitive to a beginner, then it will provide an excellent developer experience to a more experienced developer. We all benefit by centering on beginners.
Some examples
An easy one
Let's take code examples as an example. (Obviously, I ❤️ examples. Should I say "example" again?)
Do you know who loves code examples? Every developer, not just beginners. Years ago, while I was working at Keen IO, a data analytics API company, we surveyed our community of users. The biggest thing they wanted more of was: Examples! These were often fairly senior folks on engineering teams building on top of our API. It wasn't just the early career folks. And it wasn't like we had no code examples; we definitely did, but it was just something really important to all developers.
This, of course, assumes that you want other folks outside of your immediate team to use the API and view the API as a "product." See Marsh's post.
A more complicated one
Let's take another example that is more on the API interface level and a bit more complicated: Parameter names.
If your team creates an API with a lot of internal jargon or outdated product names that make their way into parameter names, it is going to be a bad experience for all developers. Maybe some of the more experienced developers will be able to navigate their way through this, but it will cause them added headaches and slow them down. ("Wtf does blobs mean again?")
As developers, it is really easy to project onto our developer users. I often see this tendency in B2D (companies that sell to developers) the most. They believe as developers, it makes sense to them or is the "right" solution, so it should work for all, or at least a lot of other developers. It can be really dangerous and confuse users.
It is a great example of the "false-consensus effect." The "false-consensus effect refers to people’s tendency to assume that others share their beliefs and will behave similarly in a given context." Source: You Are Not the User: The False-Consensus Effect I generally refer to it as the "curse of knowledge" because the producers of an API have all of the knowledge, and this knowledge often curses them causing them to not be able to see what it is like to not have this knowledge and not know what all of those dang parameter names mean.
Internal data models are an implementation detail. When it is the model for the API, it's usually not a great experience. If the API is the "product," it should be treated like a product rather than just a reflection of the database.
And honestly, I don't blame them! I have experienced the curse. As API producers, we know the internals, we write the endpoints, and we know how they work. But users don't. The first step is to acknowledge it. It is much easier to solve when you know it is there. The second step is to actively work through it. Ask people who don't have the same knowledge or experience to review an API design. Ask beta users to give you feedback on areas that could be improved before the API is live. Have you exposed the unneeded complexity that the API was supposed to be solving in the first place?
A more specific example I have seen with parameter names is terms that appear nowhere in a visual UI or other areas of the product start appearing in the public API. This can be a great barometer for whether something is badly named in an API and should potentially be changed for an external user. (There are, of course, exceptions to this rule.)
Does it flow?
My last example is a bit more fluffy: The flow.
An API is like a pile of well-loved Lego blocks. Sometimes, those pieces fit together nicely; other times, some of the pieces got chewed on by the family puppy and don't fit together nicely. 🐶
When you get a response from one endpoint, can you easily use part of that response in the next endpoint's request? Or do you have to know that you need to call another endpoint to get more information that would have been obvious in the first endpoint? (By the way, I'm not going to make this into a hypermedia blog post. 😉)
Often, when I am testing out a new API that is going to be made publicly available, I want to build something to see how it "flows." A better "flow" from endpoint to endpoint helps all developers, not just beginners.
I want to complete a set of actions with the least number of API requests possible, so I'm often looking for ways to reduce the number of GET operations that are needed. I also find reusing well-designed models in an API design can accomplish this.
Meet developers where they are
So, hopefully, this gives you a bit more inspiration for putting a focus on beginners in future API work. I just want to end on this phrase that I regularly repeat to myself in a lot of different types of work: Meet developers where they are. This whole blog post has been about that, and hopefully, you'll be a little inspired to do the same.
Additional notes
A random RFC I am watching for the future
Problem Details for HTTP APIs 👀
Error codes are a blessing and a curse for clear communication. On the one hand, they are super useful, but on the other hand, we have to come up with a consistent way to communicate errors. I love the idea of having more universal machine-readable details of errors in HTTP response content, so it isn't up to the user to figure out vague error messages or navigate custom error formats.