Should our developer experience (DX) be build on top of API documentation, SDKs, libraries or command-line interface?
The tools options for API providers and consumers enable full or partial generation of documentation, server code, client code, SDKs and much more. Does it make sense to create SDKs or libraries for all of the APIs? Should we offer command-line interface too? Would excellent API documentation be enough? What about plugins? Answer to the questions depends of the API or service offering and business plan.
These are the topics I need to consider too while acting as Platform Developer eXperience lead for Platform of Trust. In this article I will discuss the above mentioned questions from developer experience point of view. This article is part of the forthcoming book Build for Developers — application Developers as Customers in API Economy.
Technical strategy options
Technical approaches to offer great developer experience can be devided to five options. The options are non-exclusive and sometimes exist side by side:
- API-driven (example Twitter, Sendgrid, Soundcloud)
- Library/component-driven (example Stripe, Pusher, Todoist, Twilio, Soundcloud, Travis)
- SDK-driven (example Firebase, AWS SDK for Python (Boto3))
- Command line interface-driven aka CLI (example AWS, Alexa, Twitter)
- Plugins driven (example Stripe)
REST APIs are said to be so easy to consume that all else is obsolete. That might be the case occasionally and often true with single APIs. If your service is based on one API and it’s easy to use, then all you need is clear priced plans, great onboarding process with excellent documentation. That will take you far. Good examples of pretty good API documentations can be found easily.
The signifigance of API docs for developer experience has been understood by API providers and thus documentation quality has improved during the last years. Poor or outdated API documentation is the biggest showstopper for any API consumer and most common reason to look for alternatives. Also the amount of ready-made tools and services for generating excellent documentation has grown. These two factors have influenced significantly to the API docs offering.
The three column API docs formatting is considered as one of the developer friendly approaches and is used by multiple succesfull API providers. The first column on the left is index, in the middle is the desctiption and details. Lastly on the right developer can see code examples with various programming languages. The topic of API docs was discussed in details in previous post.
Another feature in API docs is live testing and that seems to get more popularity. With help of the live console (separately from docs or built-in to it) offers easy testing and exploring of the API at hand.
There’s a famous old quote by Martin Golding: “Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.” I modified it to match current situation in application development:
“Always develop and document your API as if the guy who ends up consuming your API will be a violent psychopath who knows where you live.”
If your service is a platform or even resembles platform and consuming the services requires use of multiple APIs, then you need to consider other above listed options. Lets have a closer look at the other options.
Stripe pushes libraries instead of their APIs. Why Stripe has selected libary driven strategy instead of APIs? My guess is that offering services like Stripe with pure APIs would be more complex for the developers. Libraries hide the complexity and combine the features provided by APIs into a single easy to use “5 lines of code” developer experience.
Since the libraries are created for multiple programming languages, they can be used in various contexts regardless of for example operating system or hardware. The library approach is visible in the code examples provided by Pusher in the frontpage.
Most of the library-driven service providers offer one or a few official libraries and promote community-driven libraries. Stripe has 8 official libraries. Community has created at least 27 libraries more.
Some providers seem to go to the extreme with official libraries. For example Pusher lists 24 libraries developed by community members. On top of that Pusher provides 14 official client and server libraries.
Amazon AWS and Alexa in turn seems to favour CLI approach. Also Twitter pushes CLI app called twurl, which is a “command-line application that can be used to make authenticated requests to the Twitter platform. Twurl is like curl, except that it abstracts away OAuth details once you configure it with your keys.” Twitter’s CLI tool is more for learning and exploring purposes, not for production use. For production use, developer is pushed towards different Twitter APIs.
Building CLI just for the sake of offering learning and exploring your APIs might not make sense. There are options such as Postman. Instead of offering CLI app, you can offer Postman collections, which can be used to learn and explore your APIs. This is the approach for example Nordea bank has selected.
Situation is completely different in Amazon’s case, where CLI is the tool to operate with production services in Amazon AWS. The different purpose of the CLI tool can be explained with the offerings of these two companies. AWS offering is more or less enabling services eg make application development easier, faster and scalable. Powerfull CLI tool enables automation as well as complex management tasks. Twitter’s offering is closer to enduser applications and enable methods to access user tweet stream, advertising and analysis.
Pusher is another company which provides CLI for developers. The purpose of CLI is “a tool that is designed to make your experience while developing Pusher powered applications easier. While it is definitely not necessary to develop great apps, it can help speed up certain workflows and aid debugging.” With the CLI you can list your Pusher apps as well as their tokens, subscribe to channels and see events, trigger events on a given channel, run a demo authorisation server to make debugging private channel using apps easier and generate client and server code with your keys prefilled. Pusher provides also chatkit, which enables easy in-app messaging experience development.
Last option is to provide ready-made plugins to various platforms. Plugins and add-ons are often nocode style. In other words, to get started coding is not required. The advantage of plugins is that they have lower learning curve and the audience is much larger.
An example is Stripe which provides (or lists) plugins for Salesforce, shopware and Prestashop. In addition, the platforms for which the plugins are for offer distribution channel for it. Just like with libraries, the community has created some more plugins which are listed in Stripe’s website.
Want to know more?
More about developer experience in forthcoming book https://buildfordevelopers.com/. Developer focused advisory board has participated in evaluating this article. They also provided good examples from real life experiences. The same board is Build for Developers book advisory board. Thank you again Viljami Kuosmanen, Jani Karhunen and Janne Uggeldahl.
As part of my job at Platform of Trust I’m also promoting API Economy. Thus I’m giving expert presentations in events and for staff at companies. Get in touch and book me to your event. Contact details can be Linkedin profile.