Early in my career, I spent time writing Linux kernel modules and drivers in C using a realtime framework. To understand the functions and library utilities at my disposal, I had printed out the official documentation in all its glory. Printing it took an entire day, and I used a three hole punch to put it into a big, fat binder.
Back when a binder like this would have been relevant, there was a pretty colorful acronym that used to be tossed around as freely as the term “pull request” is now. The vanilla version of this phrase is “RTM”, which stands for “read the manual.” Whether this or the colorful version, the message and tone are clear: frustrated API developers are telling their users to read the manual before bothering them with dumb questions.
Using another developer’s code was a bit like taking a college course. You’d be given study materials, and expected to demonstrate your mastery relatively quickly. It went without saying that a lot of hard work was required to succeed.
I don’t miss those days.
We don’t read instruction manuals anymore; sometimes we don’t even get them. When we buy electronics, we expect them to have little tutorials taking us through their features. When we download apps, we promptly delete them if it’s not obvious what to do next. And, when it comes to APIs, if they’re frustrating or confusing, we look elsewhere.
Back when I was using RTAI to program my drivers, l had no choice about what framework to use, so there was no motivation for its authors to go out of their way to make my life easy. Users today are way more selective, demanding ease of use, ease of understanding, accessibility of information, and a pleasant overall experience. These days, if you’re writing an API, your competition is fierce, which means that you need to provide constant answers to the question, “why should I use your API?” Here are some ways to make sure yours answers that question satisfactorily.
“When we download apps, we promptly delete them if it’s not obvious what to do next. And, when it comes to APIs, if they’re frustrating or confusing, we look elsewhere.”
Make it Simple
First up, let’s talk about the API itself. One of the most frequent kinds of engagements that I’ve had over the last few years as a consultant is what’s often described as “craftsmanship coaching.” Clients are often most interested in practices like automated testing, but it really boils down, at its core, to helping teams write clean, maintainable code. And the key to clean, maintainable code, in a word, is clarity.
Be clear in your naming so that users understand exactly what to expect from a method call. They’ll be much happier with int ComputeSalesTaxFor(Invoice rawInvoice) than int Process(Invoice i). Put yourself in their shoes when writing methods, functions, endpoints, etc – would the intent be clear to you if you were new to this? Another important consideration is not to paralyze your users with options. It may feel like you're being responsible when you offer users every option they might potentially find useful, but it really tends to lead to confusion. It’s no accident that user experience has steered us away from endlessly flexible applications with dozens and dozens of “Advanced Settings." Sure, 1 in 100 users may be annoyed that they can’t compute the sales tax under the hypothetical “Fair Tax” scheme and using Bitcoin, but the overwhelming majority of your users just want plain old ComputeSalesTaxForInvoice(Invoice rawInvoice) and will be annoyed if they have to figure out what to do for a bunch of Boolean flags or settings objects.
And finally, be sure to form and offer consistent, clear abstractions, and don’t be weird. If your API allows you to compute sales tax and add it to an invoice as a line item, don’t force users who want to remove the sales tax to compute it again and then add it as a negative. If you can add line items, provide support for items to be removed if permissible via your architectural design. A good way to gauge whether or not you’re doing this well is to grab developers not familiar with what you’re doing and ask operations they would expect to see, based on what you have, and whether the existing operations behave the way they expect.
A clean, concise API design doesn’t take the place of documentation, but dramatically reduces the need for verbosity and over-compensation in the documentation department. An API that is straightforward will imbue its clarity into the documentation and ultimately into the code that developers write around that API. Start with as simple of a design as possible, but no simpler.
Dogfood Your Own Designs
When building multiple APIs that may be used in combination together, it is important to consider how they orchestrate and translate between each other. Make sure that you strike a balance between good design atomicity for each API with respect to how they all work together in the final code that developers write to implement their solution. If you have lots of ‘little services’, your design decisions and tools need to reflect that you thought about this up front.
The easiest way to strike this balance is to test your own designs. Take the 5 minutes to write some integration code that uses your APIs in combination with each other in order to flesh out the most likely and obvious awkward combinations and any glaring omissions from an outside developer’s perspective. Also keeping a goal in mind along the way, that it’s the API consumer experience which is most likely to drive or tank your API’s adoption, is as easy as writing this down on a sticky note and putting it somewhere visible 24/7: “My API is more for them than me”.
A term we use here at SmartBear is ‘orchestration testing’ to exercise the above principal of dogfooding API design through rapid testing activities. This new style of testing is especially important with the increasing adoption of Microservice-style approaches, which have high potentials for creating significant fragmentation in your API landscape. The more ‘little APIs’ there are, the more there is to combine, test, manage, and monitor.
Be Available and Cultivate a Community
Say you’ve built a nice clean API over a useful product for your users. That’s an excellent and important first step, but you aren’t done. Releasing it and acquiring a user base may be an operations and sales consideration, but you need to take an active role in creating a community around your service and its API.
First and foremost, this means availability. Make sure that when users have questions those questions get answered, and quickly. These days, that requires more than a customer support email address. Being available over social media and participating in conversations about your product is crucial.
You don’t just want to answer questions and provide support, though. The idea in general is to build a community around your product and its API. You’ll know you’re on the right track when someone posts a question on Twitter and the answer comes from another person not affiliated with your team in any way.
Provide Examples!
This is absolutely, positively the most crucial step you can take to ensure that your API is clear and pleasing to your users. Building a nice, clean API will make it pleasing to users and building a community will help remove any frustrations that remain, but examples are paramount.
Speaking of examples, Trello’s API documentation is awesome, providing a working example of the API within the browser with no effort.
As I said earlier, gone are the days of poring over man pages and gigantic usage documents. Users now learn by experimentation. They download your library or hit your endpoint and start playing with it. Even with a nice, clear API, they’re going to have questions and get stuck on things. Providing examples of how to achieve common tasks takes them from fumbling their way through it to starting from success and building on that success via tweaks.
There is nothing more important for an API author than helping users create success every step of the way.
Provide an API Descriptor
Developers and end-users aren’t the only consumers of your API. 3rd party frameworks, integrations, and tools are often much easier to use if you provide a machine-readable API descriptor (like Swagger for REST or WSDL for SOAP). But what is an API descriptor anyway?
API descriptions are a portable summary of how your APIs work. They’re information that helps to describe the behaviors, schema, and other details of a web service separate from its runtime implementation.
In other words, you can hand off an API description to other team members, partners, or integrators as a way to help them build against what your API looks like…without having to stand up your actual API in advance. This can be a file or a document accessible from a URL, but either way, its contents conform to some well-known standard for describing APIs and define what your service is available to do for the outside world.
The best part is that, because your API descriptor is machine-readable, it’s not just good for consumption; it can be used to generate code, mocks, documentation, SDKs, and satisfy a whole bunch of other valuable use cases in the API design lifecycle.
Even if you don’t have a descriptor for your API yet, chances are good that it’s really easy to generate one and start benefitting from immediately. Many framework-specific solutions help you to augment the API code you’re already writing to emit an API description document just like WSDL is typically shipped with SOAP style web services. Examples of this are ‘swagger-node’ for APIs written in Node.js, ‘swagger4j’ for java APIs, and ‘grpc-gateway’ which includes the ability to emit a Swagger doc for services which use Google’s GRPC framework.
Why Should I Use Your API?
Clearly, after my description above, I’m a programmer. I’m a programmer with a problem to solve, and your product will solve it for me. But I don’t know it yet.
I’m going to Google, and I’m going to find your product alongside 20 other, similar solutions. I’m going to download it and try it, and, at the first bit of resistance, I’m going to quit and move on to the next option.
You can say I’m fickle and you can tell me to read the manual, but it won’t matter. You’ve lost a sale. And my use of your API makes sure that the paycheck keep going to the right places. As you write your API and socialize it with your user base, always have in the back of your mind a hypothetical user asking the question, “So, why should I use this API?” Your passion is your biggest differentiator against other competitors; use it wherever you can in your API and it will show consumers that your API is worth using.