It sounds like what you're describing is very similar to Hydra[1], which builds upon JSON-LD[2], which builds upon schema.org.<p>JSON-LD provides a vocabulary (schema) for linking various documents together, so you can for example link a blog post document directly to its author. Hydra then provides a vocabulary that lets you describe how to fetch that author document, what fields are required to create a new author object, and how to update the blog post to instead link to that new author. In this case, both "author" and "blog post" can be their respective schema.org documents.<p>[1]: <a href="http://www.hydra-cg.com/" rel="nofollow">http://www.hydra-cg.com/</a>
[2]: <a href="http://json-ld.org/" rel="nofollow">http://json-ld.org/</a>
> Then you automatically assume it’s a REST API using JSON payloads. Who’s doing anything else nowadays?<p>I'm seeing people using GraphQL[1] more these days, which also solves the problem of API schema discovery because it's one endpoint with built-in introspection[2].<p>[1] <a href="https://graph.cool/" rel="nofollow">https://graph.cool/</a><p>[2] <a href="http://graphql.org/learn/introspection/" rel="nofollow">http://graphql.org/learn/introspection/</a>
I wonder if the author knows about Swagger specs; They also started the OpenAPI initiative[0].<p>I now have wrapped a couple of API's in swagger and using swagger-ui to create beautiful interactive api docs for users.<p>Moving forward I'm going to wrap most of our legacy systems around a swagger spec'ed API and discontinue any alternative access to these systems as time goes by.<p>[0]: <a href="http://swagger.io/introducing-the-open-api-initiative/" rel="nofollow">http://swagger.io/introducing-the-open-api-initiative/</a>
We are working on a IBM "catalog" at IBM Research called API Harmony: <a href="https://apiharmony-open.mybluemix.net/" rel="nofollow">https://apiharmony-open.mybluemix.net/</a><p>One of our goals is to mine information about APIs, rather than relying on user input (hence the "catalog"). We still have a long way to go, though. In Web API land, many things follow a power-law distribution: for a few well-known APIs, a lot of information can be found (<a href="https://apiharmony-open.mybluemix.net/apis/instagram" rel="nofollow">https://apiharmony-open.mybluemix.net/apis/instagram</a>). For many other APIs, information is sparse and hard to mine.<p>Adding Schema.org (or similar) annotations would help. But it may be as hard to convince providers to do this, as it is to convince them to write OpenAPI specifications (or similar).
I put together a side project some time ago that allows you to retrieve and display arbitrary API endpoints, to create a dashboard of realtime data.<p>One of the bigger challenges was finding appropriate APIs to use. The idea being that it had to make sense as a realtime datapoint. Current temperature in California is one example.<p>Part of the solution I tried for the end user was to add a searchable database of APIs, but I never found many that had that kind of realtime datapoint. The majority of use cases for APIs seems to be CRUD apps, authentication, unchanging datasets, or really specific once off data transforms.<p>I feel like that's a bummer, as I really love the idea of being able to build up a dashboard of random data points about the world that interest me. The number of astronauts currently in space, the temperature somewhere I like to visit, the traffic density on specific roads. All retrievable individually from various apps, but not in one scifi intelligence center style place.<p>For anyone interested, the site was <a href="https://apiblocks.com" rel="nofollow">https://apiblocks.com</a>
Interesting thoughts. I've always liked if we could have something like an `api.txt` file on a website, just like we have a `sitemap` file.<p>The `api.txt` can simply be a text-based listing of links to API descriptions for all APIs exposed by that site publicly. Most API description formats already allow for the API name, category, endpoints, etc. so no need to reinvent the wheel there. A good idea would be to add the `<link rel="api" href="api.txt" />` tag on the webpage too. This would make discovery and cataloging much easier.<p>Some API cataloging sites have come up with interesting ideas. For example, there is a service <a href="https://sdks.io/" rel="nofollow">https://sdks.io/</a> that can automatically generate SDKs right out of the API descriptions that they have crawled. It is powered by <a href="https://apimatic.io/" rel="nofollow">https://apimatic.io/</a>
I find it strange that people regard APIs as their own thing. I have never "searched the web" for "email APIs", in fact that whole sentence just sounds amateurish. Similarly what is all this tooling he refers to? WTF is an "API console"? Is that not curl?<p>One time, while interviewing a candidate, I picked a random buzzword on his resume (which happened to be API) and asked him to talk about it for a bit. He immediately launched into a mini-rant about all these crazy details with APIs that seemed to be foregone conclusions. Do people actually agonize over whether the API speaks XML or JSON? Or fret over the lack of a console? Are we talking about the same thing? You have an endpoint, you send it a request, you get back some data. WOW SO HARD!
I am pretty sure there are a few API marketplaces out there where its easy to see pricing and code all at once, without having to browse around like a mad person, just like amazon has done it for shopping, with reviews, ratings and q&a.
While a lot of smart people are looking at this, I wanted to ask: does anyone know of any viable projects that build semantic data from existing websites?<p>I have experience with Open Graph <a href="http://ogp.me/" rel="nofollow">http://ogp.me/</a> and oEmbed <a href="http://oembed.com/" rel="nofollow">http://oembed.com/</a> but something about humans having to manually categorize a site has never sat right with me. We should be able to grok structure from sites by how other sites refer to them, similar to what Google does. This may be related to open source search, I don't know.
This looks really great for discoverability that works within the web platform already, without the need for inventing a new format [0].<p>However, I'm not sure if this goes far enough. There exist some formats for describing what APIs can do in natural language, though I'm not convinced that they're really that useful [1][2].<p>[0] <a href="http://apisjson.org" rel="nofollow">http://apisjson.org</a>
[1] <a href="http://alps.io" rel="nofollow">http://alps.io</a>
[2] <a href="http://restdesc.org" rel="nofollow">http://restdesc.org</a>
What about <a href="https://schema.org/APIReference" rel="nofollow">https://schema.org/APIReference</a> ? Doesn't seem to be widely used, but exists.
Google supports around seven Schema.org entity types (<a href="https://developers.google.com/search/docs/guides/mark-up-content" rel="nofollow">https://developers.google.com/search/docs/guides/mark-up-con...</a>). I think they look at the user segments and people looking for APIs is not their main audience. Especially nowadays when AI and data science is much cooler than just software engineering ;-)
We discussed a similar problem with regard to the availability of swaggers and providers willing to do so
<a href="https://news.ycombinator.com/item?id=11583377" rel="nofollow">https://news.ycombinator.com/item?id=11583377</a>
<i>> But why does searching for APIs and restaurants differ so much?</i><p>Because--oh I don't know--APIs aren't restaurants?<p>Is this really a problem, or is this a tool to help lazy blub developers be even lazier and blubbier?<p>If you care enough about an API to worry about what things it does via the docs--and why aren't you using a client lib anyways?--then you care too much to be satisfied with a simple sketch of the API via Google search results.