In the first post in the #100DaysDX series I wrote about developer experience and discussed the definition found in academic research. Since the blog is about DX, then the core concept is deemed to be discussed from multiple angles and occasions.
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 question depends on the API or service offering and business plan.
Now you might have a product based on APIs or one API. Now what? You probably want it to be used and commercialized. Building your API is only the beginning. APIs are the building blocks of other growth boosting technologies. Technical approaches to developer experience driven growth can be divided to five. 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 (example AWS, Alexa, Twitter)
- Plugins (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 documentation can be found easily.
The significance 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 successful API providers. The first column on the left is index, in the middle is the description and details. Lastly on the right developer can see code examples with various programming languages. Another feature in API docs is live testing and that seems to get more popularity. With the 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. Let’s have a closer look at the other options.
Stripe pushes libraries instead of their APIs. Why Stripe has selected library 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.
Soundcloud provides “API wrappers” for Python and Ruby, which despite the rhetorics used seems to be library-driven approach.
Most of the library-driven service providers offer one or a few official libraries and promote community-driven libraries. Some providers seem to go to the extreme in 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. Powerful CLI tool enables automation as well as complex management tasks. Twitter’s offering is closer to end user 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. To take advantage of plugins has lower barrier and the audience is much larger. In addition, the platform for which the plugins are for offer distribution channel for it.
An example is Stripe which provides (or lists) plugins for Salesforce, Shopware and Prestashop. Just like with libraries, the community has created some more plugins which are listed in Stripe’s website.
Combination of the above
Of course reality never is black and white. Often the strategy is 2-3 options of the above combined.
Some more to read from 100 Days DX
- #85 - Great Developer eXperience requires fluent internal workflow
- #84 - Theory of Economics of Developer eXperience
- #83 - The Space of API Design Decisions is missing
- #82 - Purpose of API Evaluation Framework
- #81 - Should We Move to Stack Overflow?
- #80 - Four data driven ideas for improving API documentation
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!