In addition to spending our time creating delightful APIs for our users, we also participate in events with other API-makers.
In October, we were at APItheDocs in Amsterdam to present some sessions of our own. One talk that we really enjoyed was the "What Makes an API Product Successful?" talk from Anthony Roux, so we thought we'd share a recap of the talk.
If you're really keen you can watch the video of the talk:
Anthony's talk covered a series of points (eight in total) that he felt were important to the success of an API as a product. We felt that some of them really resonated with the work we're already doing and others gave us some food for thought on things we'd love to improve on. All in all, it was a great mix of points.
By making sure that prospects can access all the documentation they will need to work with the application, you can increase their confidence in choosing your API as their solution.
All our API reference documentation is also available as OpenAPI specifications and we hope that also helps developers to be more clear both when exploring our offerings and also when doing the actual integration and maintenance of the applications they build.
Including status pages, pricing and terms and conditions in the "openness is required" category is clearly key to the work at Amadeus, and it is for us too.
We're very proud of our award-winning* documentation and developer portal https://developer.nexmo.com/ We combine API reference docs with lots of code snippets for a variety of tech stacks, high-level guides and also some longer-form tutorials to work through a particular application step-by-step.
*We really are award-winning! See if you can spot us here https://pronovix.com/blog/devportal-awards-2019
Make the signup process very easy and fast so that the user can begin to explore as quickly as possible.
Anthony's advice to defer as much data collection as possible was very valuable. It also made me think of the one and only @cbetta's advice from another excellent talk that I saw last year "Make sure you register to use your API often!".
Keeping an eye on the signup process and being aware of how the user is experiencing it, is a key element of Developer Experience.
Anthony's "Rule of Three" for target on-boarding experience:
- 3 seconds to understand an API
- 30 seconds to create an account
- 3 minutes to do the first API call
If only all APIs were created with this in mind!
Examples and Demos
This was very nicely done and I enjoyed the emphasis on having open-source and executable code samples available.
We hold collections of executable code samples and then pull them into our developer documentation as we need them - with a link back to the "real" code on GitHub. This helps us to maintain the code samples collection and also allows developers to go and see the context of the code if they need it.
Having an SDK can really accelerate a developer's work in integrating with an API.
Like us, Amadeus have detailed API descriptions of their APIs in OpenAPI format and Anthony gave some great advice on the balance between auto-generated SDKs and delightful, artisanal, handmade solutions. With our 6 (and an unofficial seventh) SDKs, I was all ears for this section and it was great to hear experiences from others solving similar problems.
Offering a limited free trial to all API users is a really good way to help developers investigate your service.
There might be a low quota or for example, we only allow the use of a small number of test phone numbers when an account is in this phase. Developers often won't have access to the company credit card when they are only prototyping, so make sure having a card isn't a requirement for a little experimentation!
Keep the pricing model simple and to offer a choice of payment methods. Pay as you go works well especially for customers that might start small and then grow.
The final section is a topic close to our hearts: support.
Be clear to users about how they can get contact you for support and how they can contact you in general.
Anthony's strong recommendation was to use public platforms for support, for example, Stack Overflow, so that when you answer the question for one user, other users will be able to find the same answer.
He also recommended using an FAQ and actively updating it. This, along with all sorts of documentation features such as a clear feedback mechanism will really help to understand how the user's experience is working out.
Being present at events about our craft as well as just to interact with customers is really important to us as a team; it continues our professional development and brings us into contact with our peers (even more of them, we're a large team by ourselves!).
This talk was definitely one of my favourite sessions from APItheDocs, thanks, Anthony!