Creating a smooth onramp is key to building a successful user community around your APIs. Here are four ways to help your users connect quickly and easily.
A key success metric for any API is the number of systems that connect to it. Those consuming systems represent the API’s community, but they don’t just appear from nowhere. Onboarding and managing an API community takes a lot of thought and craft, and even something of a cultural shift on the part of the API provider.
In this blog I want to look at four best practices for building a stable, long-lasting community—from initial onboarding to long-term management. As we’ll see, it all boils down to something I call “Engineer Experience” (EnX), where the ease of connecting to and day to day operation of using the API is top of mind.
1. Build with industry-standard technologies
As I mentioned in my last blog, a common source of friction in the Engineer Experience is connecting to an API that exposes an unfamiliar or confusing technology stack. If your API is built using proprietary technologies, or a stack that’s unusual for the industry or your implementation is not well described, engineers can end up spending a huge amount of effort in getting their heads around it. That can turn what should have been a simple integration project at their end into a weeks-long headache, and it can sometimes scupper the project completely.
This is one reason that standards have emerged around API technologies. The more standards-based the API implementation, the easier it is for external parties to connect to it. Today, those standards include REST, HTTP and JSON or XML for the build, SSL and OAuth for security, and Open API Standards (OAS) for the technical documentation. An OAS-based specification can be an incredible time-saver for engineers, for example, because they can use it to stand up a test environment in seconds, rather than the weeks it can take with a poorly-documented API.
To keep up with standards as they evolve—and to help drive them forward—it’s a good idea to join working groups like the OpenAPI Initiative, the GraphQL Foundation or the AsyncAPI Initiative. They’re a great way of discovering which standards are emerging and how you can incorporate them in your API roadmap—and they also provide opportunities to forge closer ties with the vendors behind some of the leading API management platforms, like Google, AWS and Microsoft.
2. Provide user-friendly documentation with a 5-5-5 mindset
The documentation you provide around your API is another key aspect of what I call the engineer experience or EnX. Getting it right involves putting yourself in the engineer’s shoes and thinking about what documentation you’d find helpful when connecting to an API for the first time.
Providing exemplars is one example. An exemplar is a useful piece of documentation that lets an engineer see at a glance how easy (or not) it will be to integrate with the API. It sets out at a high level what the engineer should expect to find for each API: whether they’ll be able to access accelerators or code samples, for example, and what kind of documentation will be available.
In terms of technical documentation, the OAS specification I mentioned above is very useful, as is clear descriptions of what the API is, what data it provides, and what kind of use cases it’s designed for. If the API uses industry-specific standards (like FHIR for healthcare data), it also means including details of how that standard is applied in the API, to avoid any unexpected query results.
The best type of EnX goes one further to include business-level documentation outlining the use cases the API is suitable for, and the business value it can deliver. If the engineer on the consumer side has to make a business case for connecting to the API, this can save them a lot of time.
The ultimate goal to aim for is what’s often called 5-5-5. It’s shorthand for the idea that the engineer should be able to find the API in five minutes, understand it in five hours, and have a fully-working connection up and running in five days—rather than the five weeks (or more!) it can often take.
3. Balance innovation and stability
Innovation vs. stability is one of the trickiest balancing acts from an EnX point of view. APIs are incredible vehicles for innovation, allowing data to be shared in new ways to fuel new use cases. But that, can create the temptation to update them every time a new request or use case comes along.
It’s great for the person running Application D if you’re willing to tweak your API to meet their specific data requirements. But it’s not so great for the owners of Applications A, B, and C who are already using your API, and who now have to update their implementation of it or you as the API provider need to now support backwards compatibility - over time this can become hugely complex, taking your sight off innovation entirely.
That’s why it’s important to keep the whole user community in mind when updating APIs. Too many changes can create change fatigue and lead to your API being avoided for being too much effort to maintain. But that’s not to say you can never update it. The key is to plan your updates as far in advance as you can, engage that community to help you shape and plan the roadmap, and support this with openly socialised documentation written for the needs of your consumer community.
4. Act like a product owner
If a lot of what I’ve said above sounds like the job of a product owner, that’s because it actually is. As I wrote in my last blog, when you start developing APIs for mass consumption, you’re essentially moving from a point-to-point integration mindset to an interoperability mindset, where you have the needs of a large community of systems, developers and users to consider.
The job of the API Provider then includes community engagement management, where you’re working with your consumers to understand what they want from your API and how you can make it easy for them to get it. Often that involves creating what we at Cognizant call - a Service Enablement team, focused on making API adoption as easy as possible, and ensuring the views of the community are taken into account when building the API roadmap and sharing it with them.
Talk to us for help with API onboarding
As I’ve discussed in this blog, successful API onboarding is as much about ensuring a great engineer experience as it is about providing the API itself. If you’d like to discuss ways to improve the EnX of your APIs, please get in touch.
