At the highest level discovery would clearly be “functionality for finding APIs”. Finding the right APIs for the job is what discoverability and discovery normally is understood. If you put the developer at the epicenter of all activities, you’ll notice that they might need to find more than just your API. They want docs, guides, API client settings/collections, libraries, SDKs. But lets begin with the API discovery first. There is pratically two paths: directories and search.

API catalogs have been out there for a while

All who have been involved in API Economy know programmableweb.com. That is the biggest catalog of APIs. There are other catalogs as well and new ones are born all the time.

As far as I know programmableweb only has GUI to manage inputs and additions and modification. They probably have an API, but it’s not easy to find or even public. Having a simple API to add/modify/remove APIs from catalog would be nice. Of course the frequency how often you need to add, update or delete API information is probably not too often for most of the API owners.

Then there is for example RapidAPI.com, APIs.guru OpenAPI Collection, apis.io, Mashery API Network…

KVG

In Finland we have this acronym KVG. It stands for “Kato vittu googlesta”. Free (not exactly accurate) translation is “For fuck sake, look from the google”. Search is also two folded. The developer must find what is needed but how the search engine finds the needed information is another thing. I’m not sure that Google for example reads machine-readable specs as a source of information. Enter apisjson. APIs.json is a machine readable approach that API providers can use to describe their API operations, similar to how web sites are described using sitemap.xml. The concept included a search engine (APIs.io) too. To my understanding apis.json never really took of and was not adopted widely. REST APIs are nowadays often described with OpenAPI spec and in some cases still with RAML. That is not the same as apis.json. Google crawles your developer portals and other content and probably finds relevant content. That is why we at Platform of Trust are creating API profile pages to Developer Portal.

Peer recommendation

Developers use their own networks and word of mouth is efficient way to find wanted API. It’s easy to reach out to other developers with various methods and thus recommendation and crowd intelligence is something you should take into account.

There’s more…

As I said before, the developer most likely wants to find more than just API. Github is a good resource to use when looking for helping tools and solutions around selected APIs and needs.

If the Developer Portal is well designed developer can find additional resources from there. Still that feels somewhat cumbersome to me that I should browse the web to find API related tools and services.

Zapier of APIs and tools

I started to think about automated and more direct ways to enable faster discoverability and distribution of APIs related information. I actually would like to see Zapier of APIs some day. We have plenty of APIs and the amount is growing. APIs are still in version 1, but new version is already lurking behind the corner. We have automated API documentation (with code examples) process and adding our APIs to catalogs manually and updating the information (manually) feels like a bad idea. Thus I would like to see a service which would handle the process of adding our APIs to plethora of catalogs. We provide just the machine readable spec files for the APIs and the service handles the rest.

After tossing some thoughts around this I modified the pic some more to include API client settings packages such as Postman Collections and Insomnia settings.

Process from API provider’s point of view would be:

I have a dream….

For us the above would save a lot of time and effort. Automatically generate API docs with tested code examples (done) and push new information and APIs to major catalogs. Push Insomnia package to neat registry from where API client pulls the new updated version to all API consumers. Cherry on the cake would be automatic update of our node library (coming 2020) and devs would get it updated more easily. Woooah!!

Postman enables download and link generation to collections, but I was not able to find registry for all the available collections. It might be somewhere. I did not check it for Insomnia, but I doubt that they would have such.

I know that Programmableweb tries too include all possible around the API to their catalog and they might pull it off too. The Zapier of APIs might push the library and SDK information there too and still push the same library info to npm as well. Developers search the npm repository directly from command-line.

From the API catalogs developer finds the way to our Developer Portal too. If such API client package registry (analogy would be NPM, gems, pip) would exists then developers could search and select in the desktop app for example the “Platform of Trust” package and load it without the need to search from google or any other place. Now that would be neat! That would put the developer in the center. You can do that for libraries in javascript ecosystem with NPM. Why not also for API testing clients which are becoming more and more popular.

To make the above model work something like apis.json would make everything a lot easier. I’m tempted to make another experiment of this later possibly before end of year.

Some more to read from 100 Days DX