Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

API Discovery: Can we do better?

blog.apis.guru

Post reply on HN
Print view View original

31–40 of 47 posts

Re: API Discovery: Can we do better?

#31

Post by romanhotsiy »

stephenhuey wrote: post #10
oneweekwonder wrote: post #8

Earlier quoted context omitted.

> I'm maintainer of the collection of 250+ Swagger specs for public APIs: https://github.com/APIs-guru/openapi-directory Ah cool, thanks for the link and effort. Will have a look at it as time allow. > It is pretty easy to generate Schema.org type based on Swagger/OpenAPI spec. Do you have any example or gist of a snipped of code to accomplish this? > API catalogs aren't scalable solutions for API discovery. That's w…

In case this helps, the menu for apis.guru doesn't seem to be working on my iPhone 6s in Chrome or Safari. Actually, it just doesn't work on the homepage. It works if I go to the Browse APIs page.

Thanks! That helped! Fixed now

Re: API Discovery: Can we do better?

#32

Post by Senji »

ewittern wrote: post #17

We are working on a IBM "catalog" at IBM Research called API Harmony: https://apiharmony-open.mybluemix.net/ 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 ( https://apiharmony-open.mybluemix.net…

Having a problem with industry acceptance? Throw the government at it. Either mandate or give tax breaks for following standards that the govt decrees you must meet.

When you can't use the government make a conglomerate of large companies with key hold on industries.

Re: API Discovery: Can we do better?

#33

Post by zackmorris »

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?

I have experience with Open Graph http://ogp.me/ and oEmbed http://oembed.com/ 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.

Re: API Discovery: Can we do better?

#34

Post by tomc1985 »

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?

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!

Re: API Discovery: Can we do better?

#35

Post by dozzie »

tomc1985 wrote: post #34

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? 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 immediate…

It actually can be so hard. People who call these services that mainly expose ad-hoc defined RPC interface "APIs" tend to overcomplicate their code. You get plethora of endpoint URLs, GET parameters, methods, HTTP headers, and queries encoded in JSON or XML or GraphQL or whatever sent in request body. It Ain't No Simple Thing[tm] with this many dimensions.

Re: API Discovery: Can we do better?

#36

Post by psadauskas »

tomc1985 wrote: post #34

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? 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 immediate…

It is pretty hard. One API, fine, but at several points in my career, I've had to write an "API Integration" layer for an app. For example, send notifications to Slack or Hipchat or GitHub, or poll one of a half-dozen endpoints for new info, or post some data to a half-dozen others.

Usually each service provides a client package for whatever language you're using, but sometimes its from a third-party, and they're always in different levels of maintained-ness. In Ruby, there hasn't been a single overwhelming HTTP client, just several that passed in and out of popularity, so depending on when the initial release of the gems you're using were, you'll end up with 3-6 different HTTP client implementations, each with their own way to mock requests for your tests.

On top of the client libraries, you have to spend a not-insignificant amount of time reading the service's documentation, to see how they prefer you do auth, what methods to call on the library, what the payload needs to look like, what response codes to expect, what exceptions may be raised... It is a non-trivial amount of work for each additional service. And then you get to stay on top of API updates for the dozen services you integrate with, and hope they have an email list or RSS feed so that you have some warning before they completely break your integration.

The promise of schema.org (and JSONLD, and Hydra, as I mentioned in another comment), is that if we could all just stop NIH every damn API we write because "those look too complicated, how hard can it be to just return some JSON?", then people like me, who need to integrate with several APIs, wouldn't have to waste so much time on figuring out how your special snowflake actually works.

Re: API Discovery: Can we do better?

#37

Post by OJFord »

tomc1985 wrote: post #34

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? 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 immediate…

    > 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.
What do you do if you know that you need an API for a thing, but you don't know who offers that, or who a good one is? Nothing wrong with searching for "email APIs", "payments API", "maps API", etc. - I don't know why you think that's "amateurish".

    > WTF is an "API console"? Is that not curl?
Sure, but maybe you prefer a GUI where after `GET /` you can click on 'foo' to do `GET /foo`; maybe you find that quicker and easier than using curl.

    > Do people actually agonize over whether the API speaks
    > XML or JSON?
I'm not going to throw a job interview over it, but personally I'm much more familiar with JSON and know how to handle it, so ceteris paribus, yes, I'd pick the JSON API. I'm sure others feel similarly about XML.

Re: API Discovery: Can we do better?

#38

Post by dmd »

welder wrote: post #15

> Then you automatically assume it’s a REST API using JSON payloads. Who’s doing anything else nowadays? 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]. [1] https://graph.cool/ [2] http://graphql.org/learn/introspection/

Here in "enterprise" people are still building SOAP apps, sadly.

Re: API Discovery: Can we do better?

#39

Post by ksavenkov »

Google supports around seven Schema.org entity types (https://developers.google.com/search/docs/guides/mark-up-con...). 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 ;-)

Re: API Discovery: Can we do better?

#40

Post by m3h »

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.

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 `` tag on the webpage too. This would make discovery and cataloging much easier.

Some API cataloging sites have come up with interesting ideas. For example, there is a service https://sdks.io/ that can automatically generate SDKs right out of the API descriptions that they have crawled. It is powered by https://apimatic.io/

Post reply on HN