API Developer Outreach Research for the Department of Veterans Affairs: Part 7

This is Part 7 (you can find Part 6 here) of a series on a write-up for research I conducted with my partner Skylight Digital. The team conducted a series of interviews with leading public and private sector API platforms regarding how they approached developer outreach, and then I wrote it up as a formal report, which the Skylight Digital team then edited and polished. We are looking to provide as much information as possible regarding how the VA and other federal agencies should consider crafting their API outreach efforts.

In the pages below, you will find a large number of specific suggestions culled from extensive interviews and our collective personal experience. All of these specific techniques are in service to the idea of designing the API program with the programmers who will use the API in mind at all times.

Anti-Patterns

One unorthodox part of our research involved asking API providers about the things they felt would contribute to the failure of their API platform. Below, we have collected some thoughts about the “anti-patterns” that might generate friction on the platform, chase developers away, or make things harder for everyone involved.

What We Learned

The API providers we talked to had plenty of ideas for how to run developers off and make integration with platform resources harder. We’ve provided a list of things API providers can avoid when operating their platforms and when reaching out to developers. (To be clear, each of the things presented in the list below is a bad practice — the bolded phrase is a “mistake” an API provider could make, and the text that follows further explains the nature of the poor practice.)

• Do not take a build it and they will come approach: Building API operations with tremendous resource investment before consumers ask for certain functions or resources is a poor way to achieve stable platform growth.
• Do not reach out to developers: Not being proactive about contacting developers makes it hard to build working relationships that clarify development needs.
• Hand built documentation: Providing hand-crafted, bloated, or out of date documentation is not only difficult to maintain, but it also reduces the value of the API to developers.
• Breaking changes: Changing the platform too often or too fast may introduce too many breaking changes for developers to deal with, reducing the platform’s effectiveness.
• Do not communicate: Not communicating platform operation updates leaves developers in the dark about what is happening with the very tool they rely on.
• Do not listen to your developers: Not listening to developers or including their feedback in the roadmap is sure to eventually run developers off.
• Do not measure happiness: Measure everything except for the happiness of developers, because such a metric (if you can even operationalize it as such) will never really lead to understanding if they are truly happy about how the platform is being run.
• Gated content: Putting documentation, content, and other resources behind a login or paywall, or else restricting what developers have access to, is a great way to get developers to ignore your platform.
• Do not provide a developer edition: Avoid providing developers with a set of APIs to play with simply for the sake of “experimentation.” Without being able to see the value of real, production-strength applications, users will not be building their projects on the platform any time soon.
• Do not reach out to partners: Focusing on general developers without identifying and reaching out to potential partners can rob a platform of trusted allies, who might have otherwise facilitated operations, integrations, and even broader application development.

It was clear that the API providers we interviewed were aware of the pitfalls that could jeopardize an API’s success. They provided us with a comprehensive look at what an organization should avoid when it comes to operations and investment.

What Our Thoughts Are

Adding to what the API providers mentioned during their interviews, we have some additional recommendations based on some common deficiencies we have seen. These are the areas all API providers should be investing in to strengthen their operations and to avoid the anti-patterns highlighted so far.

• Documentation: Make documentation a priority by keeping it simple, updated, and interactive for developers.
• Entry level: Ensure there is entry-level access to a platform, allowing developers to onboard without commitments or procedural friction.
• Communication: Develop a robust communication strategy for ensuring a platform has a regularly updated stream of new content about what is happening.
• Support: Ensure that a platform is supported and that API consumer’s questions are being answered in a timely manner.
• Feedback loops: Make sure that feedback loops exist and are strengthened by communication, support, and actually listening to developers’ needs.
• Evangelism: Invest in evangelism amongst leadership, partners, 3rd party developers, and all stakeholders to make sure the platform is always being spoken for.
• Observability: Insist on observability for all components involved in operating a platform to maximize measurements and comprehension of the system.
• Partners: Seek out partners. They are critical to taking the platform to the next level. Cultivate developers and applications, and produce strong partners who can help take things into the future.

We see anti-patterns as deficient areas of platform operations that can largely be avoided with proper time and resource investments.