Research and planning are crucial steps in the success of any API project. Analyzing the various intricacies that go into designing, developing and deploying APIs, as well as the business practices that come with marketing and monetization, help reduce risk and increase the likelihood of success.
Nordic APIs is one of the leading sources for information and resources on all things APIs, from the technology behind their development, to the business around API consumption. With an audience of thousands of API practitioners around the world, Nordic APIs has become one of the best known resources in the API space.
I had the privilege of speaking to Bill Doerrfeld, Editor-in-Chief of Nordic APIs, about a variety of topics related to the success of an API program. We spoke about the challenges of marketing APIs, the role of API description formats in making APIs more discoverable, the rise of the technical marketer, and much more.
You can read our full conversation below.
API definition formats like the OpenAPI continue to grow in prominence in the API space. We know how they have helped with developing APIs, but how do you think API definition formats helped in the marketing APIs?
API description formats have gained a lot of prominence and have a significant impact on the entire lifecycle of an API. They're becoming more established and common sense for a lot of companies working with APIs. Definition formats are also making “design-first” thinking a reality in the space, which helps in a better experience for developing and consuming APIs. The creation of supplementary tooling around description formats helps in their adoption as well.
Description formats are helping make APIs more accessible, thus more usable and easier to market. Formats open up a world of possibilities with complimentary tooling like documentation generation, client libraries and developer kits, all of which help in the promotion and adoption of APIs. It’s great to see how as an industry, we’ve standardized on the OpenAPI Specification, allowing all of us to have one common language of communication in the REST API world.
Definitions also make APIs portable in catalogs, thereby creating one-stop hubs for all things APIs.
When we talk about marketing APIs, we often hear about API catalogs. How effective are catalogs? Do developers really use them, or do they stick to the old fashioned route of just Googling stuff?
Catalogs are gaining prominence. Sites like ProgrammableWeb are known to receive a lot of eyeballs, making them important avenues to discover APIs. I have heard stories from developers hosting a public API, and they've had it added to a directory, and they generate leads. Catalogs are actually a lead generation mechanism, and have been known to act as an additional channel to increase footprint on the web. One great example is APIs.guru, which is gaining mindshare, and is fast becoming a Wikipedia for APIs.
While catalogs are great for the humans, they’re not machine readable. This means an extensive human friendly catalog will still have issues with portability into various search engines. This is probably the biggest advantage of having metadata associated with web APIs, since they do allow them to be crawled by search algorithms.
APIs are still added by hand curation to directories, and I hope in the future, more APIs can also automatically be indexed by various crawling algorithms.
When should marketing become a factor in the lifecycle of the API? Is it something that should come up during planning? Development?
The answer would depend on what the organization wants to do with their APIs, and how open they are as a company. If you’re a large organization, you may have the internal resources to perform a lot of testing before anything goes public. The results from these tests will give marketers some good insights, as well as time, to determine the right messaging, channel strategy and adoption models before the API is public.
In case of a startup, there may not be many resources to perform extensive beta tests. In such a scenario, it would be wise to have marketers come into the conversation early on in the planning phases of the API to give them time to determine the best marketing techniques to reach adoption goals.
What would you say are some of the challenges associated with marketing APIs?
Marketing to developers is a tricky thing because of how critical they tend to be. They need to understand the value in the quickest yet simplest way possible. Often times, this simplicity is translated to messaging, user interfaces of the landing page and even how they read and interpret the API’s documentation.
Marketing an API is difficult in another way because of the revenue cycle. It takes a while before your organization will find some tangible, measurable impact directly from the API. This value could be in the form of direct revenue, brand awareness, or repeat business. A big difference between APIs and a normal product would be the extended timeline for value creation.
It’s important to understand that APIs are high-level integrations and can touch on a lot of important components within a company’s architecture. Senior management like CPOs, CTOs, and CFOs need to understand what value an API can bring to the table. While this may seem like the space is getting a little more enterprise-y, as marketers, we should never forget the needs of our real target user – the developer. This is why documentation is so important in the marketer’s arsenal to get new consumers for the API.
Any tools you’d recommend for creating good API documentation?
I did this roundup post of 30 different documentation tools recently. I like the Swagger UI from SmartBear; it’s very well established in the space and something a lot of companies already use. I also like ReDoc, as well as Slate if you’re into the three-column documentation layout.
There are some great developer portals out there which ease the ramp up time it takes developers to consume APIs.
Do you think the ubiquity of technologies like APIs and description formats are making marketers more technical?
It’s not just marketing, it’s everyone. This is a trend across all industries and professions. Everyone needs to get a little bit more technical in order to stay relevant, including marketers, writers and entrepreneurs. There are a lot of different people involved and interested in breakthrough, disruptive technologies, which is what we can say about APIs as well. While their heads aren't completely in the code, they still must learn how to apply them to their day-to-day activities.
Maybe there might be a dedicated “API marketer” role that companies will hire for in the future?
I think that already exists, though they call them developer advocates. Marketing, unfortunately, has a bad ring to it in the developer world (laughs).
Our interview with Bill Doerrfeld is part of an ongoing series of expert interviews on the Swagger blog. Check out another popular interview with Darrel Miller, OpenAPI Initiative.