Do you remember the last time you searched for a suitable Web API? To put this into context, let’s assume you want to send emails to your users. As always, you start by typing “Email API” in Google and this is what you see:
As usual Google gives you lots of relevant search results and you start opening every site one by one. You skip typical marketing info on the front page and go straight to the “Prices” page. Then you automatically assume it’s a REST API using JSON payloads. Who’s doing anything else nowadays? Next, you proceed to answer the more interesting questions: do they have an SDK for the language you use? Do they have an API console? How is authentication handled?
You repeat the entire process all over again with the next contestant and in an hour or so you end up with bunch of open tabs and no clear understanding of which API has the best quality/price ratio. So you continue by looking for reviews on StackOverflow, Quora and reading a bunch of “10 Best Email APIs” articles.
Can it be better? Let’s skip a few hours. You have already made your choice and even done some initial integration. So after hours of continuous googling and going through endless webpages you want to treat yourself with Mexican food:
Surprise! This time Google goes beyond simple text results and presents you with a special panel with lots of useful info. You can even filter restaurants by rating and working hours. Moreover, you can read reviews right there.
But why does searching for APIs and restaurants differ so much? If you think Google is using some fancy machine-learning algorithms to extract this data, just go to a restaurant’s website and open Developer Tools:
As you can see, there is no magic here. All data is taken directly from plain old JSON wrapped in HTML. But if it’s just a matter of adding some JSON to a website why can’t API owners do the same? API owners probably know JSON better than restaurant owners 😄
Here is where everything gets trickier. For Google to understand this data it should conform to one of the predefined types from schema.org. It has dedicated types for almost everything including Zoos, TattooParlors and even Volcanoes but it lacks anything suitable for describing APIs.
To fix this I have opened an issue on the official schema.org repository to add a new “WebAPI” type. One of the maintainers asked a reasonable question which I’m too biased to answer:
I can see the basic need for something like this — I would like to see some indication of who would apply it to their sites (other than yourself of course).
We want to hear your voice!
Will it make your life easier? React with 👍 on the GitHub issue (please don’t spam with ‘+1’ comments). You are welcome to share your thoughts in a comment on this post.
Are you an API owner and would like to describe your API like this? Please leave a comment in the GitHub issue.
We understand that adding such a type to schema.org doesn’t guarantee that Google or any other search engine will adopt it immediately. This is just first step in that direction.
As a bonus, we have prepared a small teaser for you. Here is how enhanced search results for APIs could look like:
Disclaimer: The picture is 100% a product of my and Roman Hotsiy’s imagination and was sketched using Chrome Developer Tools in 20 minutes. We are not Google’s employees (however we wouldn’t mind 😄)
P.S. This article oversimplifies a lot of things. If you want to learn more about JSON-LD and Linked Data in general we recommend you start by watching this video.