[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!

[psadauskas]

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.

[tomc1985]

I've had to do this too, but the difficulties you describe are par for course with any API, web or not. People have been dealing with this shit for ages, I really don't think the HN crowd has very much to add.

[OJFord]

    > 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.

[tomc1985]

But it's all just data, is it not? I was of the opinion that any halfway-decent practitioner of computing has at least half-a-dozen different ways of getting at data or prying open its contents. Nearly every major programming environment -- particularly the ones in play with the HN crowd -- has more-than-adequate facilities for handing data in JSON, XML, and other formats. The interface to the API is usually a matter of sending the right command string over the wire, maybe you have to figure out some authentication ahead of time but most-to-all of this stuff is supposed to be write-once-run-forever. Are there additional steps in the workflow or something?

Part of the reason it is weird to see people talking about "APIs" now is because API is such a core, fundamental concept in programming that to use the term in its present context (as in, a web API which you issue commands via HTTP) does a disservice to all the other APIs out there. When people on HN talk about API considerations they seem to omit the 95% of other use cases there are for APIs outside of the realm of startups and webapps.

For example, bash could be considered an API to the Linux System Base, and bash commands use Linux's syscall API to achieve the user's ends. Syscalls are issued commands over an ABI usually handled by libc, and return data in the format prescribed by the function signature.

My TV presents an API that is accessible over USB. Granted, I am pretty sure that port is only for use by service techs, but if I wanted to I could probably hook up some electronics and figure out the programming interface. Commands are issued through the USB bus and data will (hopefully) come back in some format.

My MIDI keyboard offers an API through buttons, a little LCD panel, and MIDI-over-USB. I issue it commands through button presses on its control panel, or through MIDI or OSC protocols, and it also returns data (either a human-readable response on a LCD screen or more data over the USB wire). In both those cases I'll have to decode that data to figure out whether my command was accepted and/or what to do next.

Finally, a popular web-based CRM solution offers an event-lifecycle and data-tracking API that I have to interface with at work. I issue it commands over HTTPS and it responds in XML-over-HTTP, which like JSON, is fairly easy to parse in any number of different ways, and in any case its responses are only ever in XML so once that was written it was done with.

This is why this "API" dialogue is so strange. It is reductive and if overarching solutions are going to be prescribed than they need to take into account the wider and entire world that concept lives in. I don't see how many of the prescriptions offered help the use cases outside the HN crowd -- in fact I would argue that the author needs to go back and comb existing literature outside of web programming, because the engineering and computer science worlds have been dealing with exactly these problems for decades.

The "APIs" talked about here refer to a very specific type of product for a very specific audience; there is a bigger world out there and people seem to forget that.

  > 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".

Search for "[product name] API doc/faq/whatever" or search for code examples of people interfacing with it? It's amateurish because it reflects a clumsy and incomplete understanding of the concept of "API"

[OJFord]

I agree. I suppose it's just a matter of context, and at least in the web API context it's almost invariably taken to mean "open, accessible, and documented".

OP is about making it even easier to access that documentation.

    > Search for "[product name] API doc/faq/whatever" or search for code examples of people interfacing with it?

That's fine if you know the `[product name]`. The "email APIs" example in OP was about discovery of those product names - who offers open web APIs for email; let me compare them.

[dozzie]

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.

[tomc1985]

Maybe, but that's a problem with the design of the program, and the contents of that response. An API is only the button board, not its layout or the colors of each button. That's up to the program designer.