This is the fourth post in our Featured Guest Series! Bill Doerrfeld shares 4 key techniques that API advocates and product owners can use to increase their APIs discoverability.
If you're interested in being a part of our next series, fill out this short form and we'll get in touch with you for our next run.
The software industry has shifted to truly embrace web APIs as products, rather than ancillary services alongside the traditional business model. Because of that, API providers are naturally placing greater emphasis on marketing these services and creating a new identity that caters well to third-party developers.
If you are an API advocate or product owner, you may feel the pressure to get your service into the hands of developers by spreading the good word at hackathons, webinars, or attending API-related events. Word of mouth is an excellent tool, but before you start printing business cards, there are other actions you can take to naturally increase the discoverability of your service.
In this post, we’ll review some methods and tools that API providers can use to improve the visibility of a web API — helpful for API owners in the process of releasing a new public web API or promoting an existing one. We’ll explore:
- API portals from an SEO perspective,
- Profiling an API within developer directories,
- The viability of API discovery formats,
- and more...
Implementing these API discoverability tactics takes little effort, and little cost, and could jettison your program to new heights, hopefully bringing in more happy developers and end users in the process.
1. Create an API definition
First off, for anyone to discover your API, you will need transparent, public documentation. Using an API specification format like the OpenAPI Specification opens the door to embrace many helpful tools out there for generating beautiful documentation, including Swagger UI, ReDoc, or Slate, among others.
Having an API definition has other benefits too. It makes it easier to generate SDKs and code libraries in specific programming languages to help cater to the needs of your developer base. Widening the potential use cases makes the impact of the discovery funnel that much more broad.
2. Leverage API discovery formats to make your API machine readable
There are literally thousands of public APIs out there. That is why leaders in the API space have sought to create standardized, machine-readable descriptions of API operations to help index them, and thus make them more searchable and discoverable.
Automating the API discovery process first saw some momentum with the APIs.json project led by API Evangelist and 3Scale. The idea was to provide a meta description of API operations in a standardized way:
“APIs.json is a machine readable approach that API providers can use to describe their API operations, similar to how websites are described using sitemap.xml.”
If adopted, the APIs.json approach could be a simple boost to automatically index the thousands of APIs in existence. However, though the project has some adoption, including Fitbit and Trade.gov, it has yet to become an industry standard mechanism for making API operations more transparent.
An alluring solution to the lack of a conformable API discovery format is APIs.guru, which is slowly becoming a “Wikipedia” of APIs. The benefit to APIs.guru is that if API providers already have an API definition, they can automatically index it in the database. The APIs.guru database powers directories like Any-API, therefore spreading your API to many more potential communities.
3. Profile your API in the growing number of API directories
Finding the right API for a project can be difficult. That’s why sites have emerged to help developers sort through the chaos, and comparison shop for the perfect fit.
While the actual conversion rate has yet to be measured, it’s no doubt that adding your API to these locations can significantly increase its visibility. You can think of taking advantage of all these API databases like social media marketing; though your main traffic may come from Twitter, it doesn’t hurt to have a Facebook account either. ;)
- ProgrammableWeb: The web’s most respected source for new API releases and API industry news. Their newsletter also lists new APIs added to the directory every week.
- APIs.guru: APIs.guru is establishing itself as an open source “Wikipedia” for web APIs. It takes your API definition, indexes it, and exposes it to other sites.
- Mashape: A large API marketplace. You can index any API in the directory, even if you don’t run Mashape Kong management.
- APIs.io: If you’re following the words of the API Evangelist and have created an APIs.json file, having a presence on APIs.io should be an easy process.
- Hitch HQ: Developer users can follow APIs and be notified when they change. Hitch also works with API providers to grow their communities.
- API Harmony: IBM’s curated API collection also allows third party contributions.
- Exicon Directory: A medium sized API directory that aggregates many different industries.
- API Katalogen: A Swedish API directory with many great open data resources. May need Google translate for this one!
- SDKs.io: Profile your SDK here to increase its visibility. Powered by the developer experience platform APIMatic.
- Rapid-API.com: A growing API database with a nice interface for discovering APIs.
- Any-API: Powered by APIs.guru, offering “documentation and test consoles for over 300 public APIs.”
- API For That: Tweets new APIs added to the directory.
Profiling your API in public directories can increase the visibility of your program and open it up to new communities. Some recommend generating a Swagger/OpenAPI, RAML, or API Blueprint definition, which can be auto-generated from many API management portals.
4. Improve SEO with target keyword copy in developer home pages & docs
Another important aspect of improving discoverability is the API home page, as the keywords, content, and URLs that we feed search engines are vitally important to boosting search relevancy.
Many API providers may not realize the high value of their copy on developer home pages. Words hold the true intelligence as they inform both prospective users and machine-driven search engines. When writing copy, use a range of terminologies relevant to your niche product, and cater to geographical trends in language.
Making the developer portal human-readable with a functional description catered to non-developers is helpful as well. For example, take how Avalara describes their API in a succinct single sentence:
“Real-time tax calculation for financial applications”
Keyword optimization in our realm means researching what developers are discussing and searching for. Finding search keyword performances as well as geographic nuances can be done using a tool like Google Adwords Keyword Tool. Knowing your keywords will also guide advertising on search engines, if you decide to go that route.
When describing your API, consider increasing word count on API homepages to describe technical features, and leverage the nuances in technical jargon to help distinguish your service. For example, “Emotion Recognition API” may be a more applicable label than “Facial Detection.”
But this is only the beginning — the copy used is actually part of a larger onboarding experience that should be catered to unique developer personas. Guillaume Cabane recommends optimizing the signup process using predictive analytics, dynamic content, user testimonials, offering a self-identification option for customer support, and more to tailor the developer experience and increase lead conversion.
Other Strategies to Boost API Findability
- Use interactive consoles for testing API behaviors: Finding that an API exists is only the beginning. The next step toward developer acquisition is testing API behavior with sample requests and viewing the responses.
- Create Zap & IFTTT apps: Partnering with Zapier and/or IFTTT could open your API to usage on a massive scale. Especially relevant if you have push features (webhook, Pub/Sub, real-time/streaming) that could be used to trigger other events to help savvy end users spice up their workflows.
- Attend events: Don’t dismiss the power that hackathons, meetups, and speaking at events have to spread awareness.
- Improve learnability and developer experience: A big part of marketing an API is making the front-end as human-friendly and discoverable as possible. As your developer center acts as the locus for API learnability, make discovering new knowledge as easy as possible.
- Follow the industry: Channels like API Developer Weekly, ProgrammableWeb, the Nordic APIs blog, GET PUT POST, the Zapier engineering blog, and API Evangelist will keep you updated on industry momentum that could be critical for sustaining a relevant front face that caters to developer needs.
- Utilize dev communities for feedback: Post your API to Hacker News, Product Hunt, Beta List, or other channels to gain real-time usage and feedback. Heavybit also provides great talks and resources on developer evangelism.
- Contribute: Publish thought leadership content around your platform. Kairos does this very well by creating a publishing machine whose content supports their human analytics program.
- Separate microservices into well-bounded product front ends when applicable: If you run a metaservice with multiple APIs for separate services or varying endpoints, then it may help to segment the developer experiences for service to cater to specific niche interests.
Discoverability is Part and Parcel of the Intention Economy
The first step toward promoting any API should be taking a step back to see if it is discoverable. For history immemorial, there has been a fine line between the product and its advertising… but as consumers become more informed this dichotomy is blurring, and the web sector is leading the charge.
Developers are smart, and probably don’t need overt advertisements. Rather, SaaS services should cater to their consumer’s *intentions*, and increase the discoverability of their service to mimic their search behaviors. Focusing on improving discoverability rather than dumping funds into an advertising campaign is in line with the Intention Economy, a philosophy coined by Doc Searls that places more emphasis on the consumer opinions and intelligence in finding products.
With karma-based ranking systems in vogue on developer social channels (Hacker News, Reddit, etc.), and the growing complexity of search engine algorithms to privilege quality, evergreen content, the viability of the Intention Economy is becoming more realistic, and the hunt for APIs is an apt case study.
To review, in mid-2017, making an API truly discoverable involves keyword performance analysis, profiling in all API directories to increase the spread, leveraging API discovery formats, and creating machine readable API definitions to document your service and to leverage helpful tooling.
We have defined many ways to set your service up for discovery. Now it's up to you to tailor your experience to optimize visibility. Good luck!