Application Programming Interface (API) has become a hot buzzword in the tech world. More and more organizations are understanding the practical implications of developing an API program to reach their strategic goals. In such a setting, it’s important to better promote your API’s value and benefits in a way that makes sense to your potential users and customers.
I got a chance to sit down with Jennifer “Jen” Riggins, marketing consultant and tech storyteller at eBranding Ninja, to talk about the culture that exists among API practitioners. Jen is a prominent marketer and branding consultant in the API space. Being one of the few storytellers in the API community without a formal technical training, she offers a unique perspective into the culture that exists in the API space and discusses how important it is to tell your API’s story to a broad audience.
The Culture of API Innovation
Jen believes that interest in APIs has gained a lot of momentum in the past decade and is going to be playing a major role in shaping our future. APIs have gone mainstream in part due to the efforts of the API community to evangelize and raise awareness of the benefits of investing in the API economy. This community, consisting of API vendors, practitioners and consumers, is championed by openness and collaboration, which has led to significant development in the API space.
The blend of openness, transparency and inquisitiveness makes for a culture of innovation. This has also contributed to the growing number of new technologies that have permeated the API space in a short span of time, from API definition formats, like the OpenAPI specification, to new architectures, like Hypermedia and Graph. This general culture of collaboration is a reflection of the open source community, since a large segment of API practitioners have their roots in open source projects. To facilitate collaboration and foster faster engineering, API development platforms like SwaggerHub offer features that are conducive for teams to design and document robust APIs together.
“There’s a general trend in the tech space to give more power to the developer, to collaborate more on software projects. This was the foundation of the open source community, and is now being seen in the API community as well,” Jen said.
She says that the API community has been very welcoming and endearing, allowing members to learn and grow in the process. There’s a good mix of people from different backgrounds and skill sets involved in developing and integrating with APIs, that brings a diverse set of viewpoints into the conversation. Jen also observed that as API awareness grows, so does the geography of the community.
“It’s a very virtual community. This is partly because of the nature of the technology itself, and partly due to its roots in the open source community.”
This culture may change with the increase in competition in the API space. There’s been an high rise in investment by tech heavyweights to release API documentation and management solutions, which may likely have an effect on the general culture of openness and transparency that the API community is synonymous with.
Why APIs Need Good Storytellers
Jen raised an important point of a lack of good marketing in the API industry. Marketing is about telling the right story to the right audience so as to help them succeed in their endeavors using your products. Now that the business models of APIs have been established, it’s important to pay attention to how effectively you’re telling your API’s story to your target market. Since APIs have always had a technical bend to them, most developers focus on their API’s core technology and not the business value when marketing their API.
“The big pain point right now that the industry is facing is communication. At the base, developers are still pretty bad at promoting their APIs and translating it to a broader audience. API developers and vendors need to communicate the business value of their API to their potential customers and how it would benefit them.”
Jen continued that “A lot of API documentation and marketing omits even a basic summary of what the API helps the user to accomplish.”
She referenced an APIdays talk from a couple years ago by Andrew Seward, where he asked audience members to take a minute to describe their APIs to each other.
“Folks jumped right into describing the language and architecture driving these APIs, completely skipping the business value behind it all,” Jen said.
One big issue organizations still struggle with is understanding their core audience. Gone are the days where an API’s target audience is just tech savvy developers who will do whatever it takes to integrate with your API. An API’s audience has expanded to product managers, technical writers and marketers who want to solve a particular issue using the services distributed via the API. If the API’s value and service on how it helps solve the pain points of your target audience isn’t clear, then it will have adverse effects on its adoption. An API’s target audience encompasses a bigger segment of personas now that APIs have become business drivers, and being empathetic to these personas as you tell your API’s story is a key component to your success.
API influencers are steering the conversation toward the idea of effectively translating the value of your API services from a business perspective to customer facing messaging. Once people identify the business value, the issues of API adoption and up-sell can be better alleviated.
“Good marketing has to start from being a better advocate within your own business and sector, and only then can you advocate outside the API community. We’ve done a tremendous job in evangelizing and promoting the benefits of APIs in the tech sphere, and it’s high time we tell this story to the rest of the world,” Jen said.
Jen believes the API community needs its own stars that tell stories that resonate well with the rest of the world. People like Kin Lane (API Evangelist), Lorinda Brandon and Arnaud Lauret (API Handyman) have been actively promoting the benefits of investing in API programs to a nontechnical audience, but Jennifer feels we need more. She says we must be better marketers of not just APIs, but of each other within the community in order to increase mindshare on the benefits of the API economy.
API Documentation is an Extension of your Story
API documentation acts as an extension of your overall API message, that focuses on providing your consumers with all the right resources to get started and integrate successfully with your API. Jen believes that this message must be permeated across all facets of your API offering, and documentation is an integral part of this message. Good documentation caters to your entire target audience, and since your audience isn’t just restricted to developers in the API economy, it’s important to be prioritize and optimize your documentation accordingly.
But documentation has always been the least prioritized step in the API lifecycle, despite being the biggest conversion point for API adoption, as Jen found out when she was researching for her State of API Documentation report for 2017.
“What was really interesting after interviewing dozens of API influencers and writing the industry report on API documentation was the need for the human touch in documentation. For a short period, people were satisfied with generating Swagger documentation from an API, but soon realized there’s more needed. There’s a big demand right now for skilled tech writers that can also empathize with genuine human problems in the marketing process.”
From her conversations with numerous practitioners, Jen believes the best way to start the API documentation process is by generating a specification for your API, which will be the foundation of concrete and robust documentation. This could be using any of the popular frameworks like Swagger or API Blueprint. There’s always the problem of generating the definition for legacy-based APIs, and you can check out our free resource on some good solutions on overcoming this. Generating this definition is is no way the final step. Documentation always needs a human touch, and has to evolve into a comprehensive usage manual that guides users through every stage of the API adoption journey. Documentation can be treated as a product, and Jen reiterates that tailoring your message and API documentation to solving the overarching scenarios customers have to solve can greatly contribute to user satisfaction.
“People are Googling for your API, reading your API’s value propositions and documentation, and will be going to someone else’s API if they cannot get started with your API.”
She believes that to build first-class documentation, it needs to be a part of the API development process. Gareth Jones, principal architect of the Microsoft Graph API, echoed this point in a previous conversation about starting the development process by first documenting the overarching scenarios customers might face when using your API. With this documentation or spec-first approach, organizations can then start talking to various pilot customers on how to improve these resources to increase API usage. Treating your API documentation as a separate first-class service that helps consumers integrate faster with your offering should be a strategic priority.
The Future of the Industry
Jen believes that APIs are going to be spearheading a lot of new technologies like artificial intelligence and the Internet of Things. Due to their interconnected nature, APIs will be the backbone of a host of new innovations.
“It’s all the shiny new things that are happening that APIs are the backbone of. IoT, AI, machine learning and AR [augmented reality] will all be serviced by APIs, one way or another. There are different innovations popping up all the time that are evolving, with APIs at the center of them,” she said.
With the API economy upon us, and new technologies popping up faster than ever, the need for effective storytelling will only amplify.
My interview with Jen is part of a series of API expert interviews. Is there a topic you’d like to see us explore with an API expert? Let us know in the comments below, or tweet at us: @SwaggerHub.