Tips to Improve the Discoverability of Your API

Tips-to-Improve-the-Discoverability-of-Your-API“Build it and they will come” is certainly not the case in the API world. Even if you have a functionally brilliant service, without the right positioning your conversion rates could still be very low. Assuming you’ve made your developer program visible to the public, how should you then promote your API?

There still may be tremendous growth potential in your service if it has the right online representation. Perhaps you didn’t orchestrate your initial release launch with enough gusto, or the service isn’t positioned in a way that increases its visibility across search engines, API directories, and community forums in a way that highlights a unique value proposition.

Getting the word out by attending and speaking at events, or by holding your own hackathon can make for excellent publicity. A lot of this naturally depends on word of mouth and the human-human element — nonetheless, there is still a lot you can do online to increase the exposure and breadth of your API program to ensure all possible avenues for growth are utilized.

In this article, we dig into three inbound methods that a provider can use to improve the discoverability of their API:

  • SEO: Optimize your API homepages to make them more searchable.
  • API Directories: Promote your API by submitting to our cheat sheet of 10+ directories.
  • Service Discovery Automation: Increase discoverability with machine readable techniques.

SEO Approach: Optimization of API Homepages

The most obvious method a developer is going to use to find your API is through a Google search. SEO or Search Engine Optimization is therefore a top priority for any startup. Make your page more searchable by optimizing content and metadata so that big name search engines continually spotlight your site. As the API Economy is highly niched, keyword optimization is a close friend to many.

Keyword Frequency

Consider what a developer would search for when looking for a certain tech in your space. As an example use case, let’s say you are entering the Natural Language Processing market with an API that accepts bodies of plain text and provides statistics such as word count, word frequency, tone analysis, and performs other NLP functions. A focus keyword phrase that a potential developer consumer may search for would be “Text Analysis API.”

The number and frequency of keywords found in the copy for the top five results from a Google search for “Text Analysis” is as follows:

Company “text” “analysis” “API”
Aylien 19 (6%) 11 (3%) 13 (4%)
AlchemyAPI 2 (1%) 2 (1%) 3 (1%)
Text Razor 2 (1%) 2 (1%) 3 (1%)
Bitext 6 (2%) 6 (2%) 20 (6%)
Saplo 11 (3%) 7 (2%) 18 (5%)

Results from search performed on 5–4–2016.

Google’s algorithms for ranking content are in constant fluctuation, but as you can see above, sometimes page ranking comes down to something as simple as keyword frequency. Alyien’s presence stands out from the rest with this search as it scores high keyword density for all three search terms.

Allowing your API to soar naturally upwards in search rankings by focusing on a focus phrase, supported by a diversified portfolio of supplementary focus keywords in your site copy will be a powerful tool in your marketing arsenal. This means that having a carefully worded non-technical description of API functionality is paramount to search engine optimization.

Having good API meta data also makes you more discoverable by API-specific search engines, such as the APIfinder on APIhound.com, or engines that use the APIs.json format for discovery (more on that below).

Separate Pages that Overview Each API

Let’s take a deeper look into why Aylien performs so well in this test search. The site copy isn’t the only thing performing well, the URL https://aylien.com/text-api specifically contains two of our keywords — “text” and “analysis.” Though Aylien supplies different services (two APIs, apps, and publisher tools), they have separate home pages for their two API services — Text Analysis API & News API.

Separating service presences with dedicated developer centers that use simple, targeted URLs is a boost to SEO. This is necessary for API suites that cater to many specific services, such as Microsoft’s Cognitive Services — a library of artificial intelligence APIs. The BarChart on-demand financial market data platform takes this even a step further, isolating the public documentation of each API parameter onto unique URLs.

Separate homes pages for your multiple APIs helps organize site architecture, and widens your content impact to take advantage of specific focus keywords, opening you to a wider net of searches. Home pages per service also allow a space to introduce technology to non-developers; good example of this is the Pitney Bowes Developer Hub — for each individual API they have a page with detailed copy, and a very accessible video that communicates the value proposition for the specific function.

Don’t push the segmentation of actual documentation too far though, or you risk a decrease in usability and developer experience.

It’s in the Name

This may seems obvious, but choosing the correct product name is crucial. An API-centric company promoting a single product has the benefit of tying niche functionality into a single brand image — Wit.ai, for example, uses the Artificial Intelligence acronym (AI) within their name and domain extension. However, larger tech companies must partition multiple brand identities under one roof, thus increasing the importance of targeted product naming and service identity.

Also increase your API Marketing attempts by Understanding Your Unique Developer Consumer

Cheat Sheet of 10+ API Directories to Submit Your API to

Ok. Now we have a good take on refining brand identity and copy. Next is making sure that your API is represented in the following directories so that developers using resources other than Google are able to find them. We don’t have any numbers on traffic for these sites, but as submitting profiles is a relatively easy process, it seems worth it to increase the visibility of your API.

ProgrammableWeb

ProgrammableWeb is a great site to follow for new API releases and to search for APIs. If you want to target developers who are looking for a tech like yours, this is a solid first stop. What makes ProgrammableWeb great is that they are pretty open to featuring content from the community. There are a few things you can do on their site:

Mashape

Mashape is well known for their developer portal and analytics services for APIs and microservices. Even if you’re not using their management tools, you can still list your API on PublicAPIs.com, their extensive marketplace:

  • ADD your API profile to PublicAPIs.com
  • or PUBLISH your API with the Mashape network

apis.guru-nordicapisAPIs.guru

APIs.guru is becoming the open source Wikipedia for APIs. Since the directory is open sourced, APIs.guru has integrated with Any-API, SDKs.io, Cenit.io, and other open source software, meaning this could potentially expose you to a wide net of software developers. Anyone can add or change an API:

Other Places Where you can List your API:

  • Exicon : ADD your API to their directory in a “matter of minutes.”
  • API For That: SUBMIT a profile to this small, but curated API directory.
  • IBM API Harmony: SUBMIT your API for review with IBM’s curated third party collection.
  • Swedish API Directory by Mashup.se: SUBMIT your API to the Swedish API catalogue maintained by Andreas Krohn/ Dopter.se. Keep in mind it’s all in Swedish!
  • SDKs.io: Add your SDK to this collection of Software Development Kits.
  • APIs.io: Create an APIs.json file and register your API with APIs.io. (We’ll explain why below)
  • API Changelog: Request an API with this API monitoring site so that your API consumers have automated updates when your docs change.
  • Hitch hq helps API providers grow their community and make their platform more discoverable. They have a growing list of APIs, and providers can sign up with them to add their API to the list.
  • RapidAPI: Suggest that your API be added to this growing API marketplace here.
  • More?: Please Contact us or comment below to expand this list!

The next two aren’t exactly API directories, but smart to consider as part of a promotion strategy for web apps that have APIs.

IFTTT

If This Then That (IFTTT) is a platform where users can set triggers between web apps — if one thing happens in one app it will influence a function on another app. The cool thing is that IFTTT does accept requests to build a new channel on their platform if your app has a public API. If you want to get your functionality and branding in front non-developers, this could be a good outlet:

  • SUBMIT a channel request with IFTTT.

Zapier

Zapier is similarly a platform where users can create home brewed concoctions to automate the sharing of data between various web apps. If you want to submit your app into the Zapier marketplace, it’s actually possible:

In our last article on API discovery we listed 11 ways to find APIs from the developer’s perspective. Note that however, not all those API directories allow you to submit profiles — some are search consoles for API management networks like Apigee or Mashery. Others are proprietary API collections (IBM library, Google Discovery Service, etc.). Thus, in this article we have listed networks that any API provider could submit to.

Service Discovery Automation

API discovery is the sum total of processes a developer uses to search for, find, and research APIs. As described above, this typically starts with a Google search, or via the aforementioned directories. But more than often, successful programs get traction through a bit of luck and word of mouth.

After a developer has found a few potential services, there are still many factors that make comparing similar APIs a complex affair. Potential users must consider things like licensing costs, rate limiting, data formats, usage policies, authorization methods, and documentation types, and then must experiment with actual code implementation and testing before deciding on a single service to use.

Bruno Pedro, API specialist and co-founder of Hitch hq, sees the entire process of API discovery as thus:

  1. Initial Searching: Google, directories.
  2. Documentation: Understanding API parameters.
  3. User Provisioning: Must authorize/authenticate with the service by some means. SAML, OAuth, etc.
  4. Code Generation: Consumer will want to work with the language of their choice, so SDKs, ready-to-use libraries are generated from API definition.
  5. Integration: Once API is consumed in app, it must be monitored for uptime and changes.

The question is, how can we automate certain parts of this discovery process to make finding the right service more easy?As we’ve outlined before, solutions exist to automate code generation, and there are many API monitoring solutions on the market as well.

But the other points are not as easily automated.

The hope is that by creating a machine readable and consumable meta format for describing APIs, machines will easily understand what an API is capable of doing, and will be able to describe the human-facing documentation, the price, signup process, authorization mechanism, endpoints, and more. That’s where APIs.json comes in — a project that hopes to combine these items into a single format to make all APIs more discoverable.

APIs.json

The open APIs.json format, supported by 3scale and API Evangelist, is an emerging format for describing API operations to enable automated discoverability by software robots. The idea is novel because it is the first approach to standardizing an API’s operational metadata.

“For each API listed, you give it a name, description, and supporting properties, which may be as simple as providing a link to your documentation, or be as complex as providing a link to a machine readable API definition in the Swagger or API Blueprint format.”

Dubbed as an index for API operations, APIs.json can be thought of as similar to how websites use a sitemap.xml file to describe site architecture.

Your APIs.json file should reside in the root of your domain. Take Fitbit’s current live implementation on https://www.fitbit.com/apis.json as an example. (Also view a detailed explanation of said Fitbit APIs.json file here). Once the APIs.json file is created, you can register it with APIs.io, an open source API search engine which currently lists over 1000 APIs.

Outside of APIs.io, APIs.json will be a driving force behind other API-specific search engines and other projects currently under development. Consumers can also create API.json files to describe the 3rd party APIs that their applications depend on. This ecosystem will even enable API brokers to act as aggregators that assemble collections of multiple APIs relevant to specific industries.

The project is still accepting feedback, but as more people use it, future standardization with a body like W3C seems possible. Many believe that indexing APIs using APIs.json will allow new tools to emerge, and be a huge leap toward standardization in the API space — so jump in on the fun now rather than later.

More on promotion: We’ve outlined what it takes to become an API advocate in our post Day in the Life of an API Evangelist

Next Up: Fine-Tuning a Launch, Developer Relations, and more

Increasing the discoverability of your API presence is an important first step toward increasing the impact of your service. But, there are still many more avenues, like hosting your own hackathon or developer summit, reaching out to press and posting on networks like Product Hunt, or establishing quality developer relations with existing customers through email, GitHub, and forums to maintain a helpful, transparent company persona. Improving your developer center with helpful tutorials, a consistently publishing blog, and more also increases onboarding and usability. There is still much to cover when it comes to API Marketing, so subscribe to our newsletter as we explore other ways to spark adoption within future articles!