I am preparing for a busy week of conversation with folks at API World, and with an inbox full of requests to meet and discuss the challenges API providers and service providers face, I want to work on preparing myself by loading up a variety of topics into my old brain. Some of the folks I’m talking with have shared questions with me to prime our conversational pump, so in my way, I figured I’d work through them here on the blog to help put these thoughts on the tip of my tongue.
API providers are always wanting more advice on how to help developers be more successful when it comes to their valuable API resources. This is a question with one answer—get out of their way at every turn. Make it dead simple to signup, obtain access keys, and begin making calls on the API you make available. As technologists, we excel at over thinking things, and assuming everyone has the same view of the landscape as we do, when in reality we suck at explaining how we got here, and are notorious for leaving obstacles in our potential consumers way. Here are the main areas I invest in when it comes to reducing friction for developers when it comes to on-boarding with our APIs.
- Documentation - Provide modern, complete, and up to date documentation for your API powered by an API definition (OpenAPI, Postman)—do not hand-roll your own documentation. Keep your summaries, and description simple, intuitive, and informative, and as yourself how you can get out of developers way with regular refinements.
- Getting Started - Craft a simple yet comprehensive getting started page for your new developers, breaking everything that is needed to get up and running. This is your opportunity to regularly revisit your on-boarding process, reduce friction, remove the sharp edges, and unnecessary steps.
- Run In Postman - If you have an OpenAPI, generate a Postman collection, and make sure it is refined, well organized, and make it available to your API developers using a Run in Postman button, allowing them to begin making calls to APIs within as few clicks as possible.
- Environment - Invest in an environment definition to accompany your Postman collection, abstracting away authentication and the variables developers need to make their first API call, and put each API to work. Providing a blueprint of everything needed to go from Run in Postman, to seeing API responses in your client.
- Signup - Make your sign up process as frictionless as possible by reducing the amount of data you require, and the number of steps needed to signup, verify your identity, add an application, and obtain API keys. Put yourself in your consumers shoes and be honest about what it should take to get access to an entry level API key.
- Sandbox - Provide a sandbox that new developers can play with, allowing developers to play with mocked APIs, complete with synthetic data. Providing a safe environment for developers to kick the tires and play with to see what is possible, then raise the bar when it comes to obtaining access to a production environment.
- Self-Service - Make everything in your API developer portal as self service as possible. Even if you need greater approval to gain access to production resources or higher rate limits, lower the bar for new users, and help them get what they need without asking. You can have greater requirements when it comes to further activating them, once you’ve successfully on-boarded them.
I will stop there. I think keeping things short and concise is an important aspect of on-boarding someone, whether it is to an API, or just to a concept. How do you reduce friction with on-boarding is a question you shouldn’t just ask once. Ask over and over until you have reduced the unnecessary steps involved in understanding what your API does, and how you get access to it. If you truly want to hone your skills in on-boarding new developers, pick twenty-five 3rd party APIs, and on-board with them. Don’t just review their developer portals and documentation, actually sign-up and get the point where you are making API calls. See what it takes to do it well, and experience what it takes to do not so well.
There is no definitive guide to on-boarding API developers. It will vary depending on the API you are offering, the consumers you are targeting, and the industry you operate in. However, there are some common practices that can help you speed up the process, and assist developers in reaching that AHA! moment much sooner. You can find these being applied in the most successful APIs out there like Stripe, Twilio, and others. The best ways in which you can refine your on-boarding practices is to learn the practices of other API providers, and to talk to your developers, and listen to the friction and challenges they encounter. If you invest in these two areas, and regularly re-ask this question, eventually you will get to a place where your on-boarding is smooth, and soothing that makes sense to a wide swath of the community that you are targeting.
