I’ve worked in the public sector of Denmark for quite a while, and that’s involved a loot of different APIs, and I’ve seen my share of the “poor-experience” examples.
It’s always worse when there isn’t an API.
That being said, the best APIs are the ones that have good understandable documentation. And I don’t mean some auto generated bullshit, but documentation that your developer can hand off to your data person and whatever project manager is ordering the information, and they’ll not only understand it, they can use it to tell your developer exactly which Y goes into X.
Beyond that you’ll want a decent test API, and you’ll want workable examples of how to make each call in JS/python/c#/java/php at the very least.
And you’ll probably still want the option for batch dumps via SFTP or whatever.
So no, I don’t think APIs are elitist, I just think most of the people who make them either suck or weren’t given enough resources to do a good job.
I disagree, Swagger is auto generated and I prefer to work with external APIs if they have Swagger documentation which allows me to easily test their API via web browser with two clicks, I don't have to open tools like Insomnia
Swagger may be autogenerated, but if the internal structure of the app is crap then you still won't have a good time. I once encountered an API which managed to have about a dozen (!) "Token" classes, all referred to as "token" in all responses but all slightly different. The docs (autogenerated, though not by swagger) helpfully informed me that "a Token is required for this request" on every request type without specifying which type of token.
If it's public data, people will "abuse" it just as well by requesting/scraping the website directly. In most cases it'll cost you more in resources when someone "abuses" the website as opposed to the API (as they'd typically make more requests and/or use more bandwidth on irrelevant things).
That’s what I was thinking. So the download is open, but the API is restricted? Then the comparison is obviously not about the API but about the restrictions.
When building a backend, I lived through the age of custom exporters. It sucked. Having an API and the providing helper calls to do stuff like download the recent month in CSV is way better.
I like having an API that both the UI and users who want to directly integrate use as it’s just simpler.
The lesson may be that just having an API is not enough unless you have a big community or ecosystem building on it (eg, AWS).
I have this feeling with Tatoeba, a sentence-translation website.
You can download all the data, sliced and diced in various ways, via their download page: https://tatoeba.org/eng/downloads - and also via perma-urls. It's easy as pie. I've written a bunch of scripts to do it.
I agree with the general point in this article, but I think aiming the problem at the "API" versus a download button is slightly missing the culprit.
I don't mind an API that allows me to easily request the entire dataset I want to grab with a single unauthenticated call. When this is possible, it's easy to create a download link for less-technical users by hard-coding a query into an href tag. The issue is when an API forces me to make a large number of queries (often tens or hundreds of thousands) to construct a relatively small dataset. Combined with rate-limiting and authentication, the whole thing becomes a nightmare to work with.
Sure, the standard API interface is great if you want to programatically interact with an external database through a custom application. But that design does not lend itself well to accessing public data for the purpose of modelling and data analysis. But, it's not the API persay that's the issue. It's the way that APIs are designed.
No, for the precise reason that whatever you think your product is, your users and customers value its data above everything else because it powers their own conversations and decision processes.
With the explanation, if you have a product without an API, I guarantee you have a conceptual gap in the value you provide and why. If your product/data is valuable, users will put up with the most terrible UXs, but if you have the shiniest UX with gaps in the underlying useful data, you've basically got a videogame.
Then you need to look at what elitism is. It's not about requiring skills or physical competence to do something, as that would mean anyone who practised something would be a so-called elitist, which is absurd. Elitism is a way people without actual status affect or pretend to be as a way to convince others without status that they are elevated. Elitism is being a poseur. When you are a member of an actual elite, there is negative value in signalling it to an outsider, the only value is to signal your membership to other insiders. So someone who makes effort to signal their status to an outsider would therefore be an elitist.
Viewed that way, an API is not a signal, it is tool that literally refines the value of your data to that which is truly useful. My next product is starting as an API, and then I'm going to add UX skins to it because if it doesn't attract users, it won't be because of the trendy symbolism in the UX, it will be because it doesn't present the real meaningful data they need.
Please, make more APIs, as value for effort on all sides, it's the best possible solution.
I mean, in this sense large highways are elitist right? They require a drivers license, which requires studying etc.
Now, I'm not saying that it's an equal metaphor in any way, but worrying about API's not being accessible enough is only valid if the given consumer is having difficulties using/consuming the specified format. You can't write a spotify client with a csv as input, just like you can't read a book in a language you don't know.
There's a sense in which APIs are elitist, but that's a misuse of terms, I think. Where I'm from, elitist has negative connotations. There's a difference, at least to me, between expert and elitist. Elitist is if you would refuse to use a download csv button, even if it fit your use case because you are a real developer who only uses APIs.
Lots of things require expertise, and conflating prerequisites and elitism seems like an overall loss for effective communication.
> An API-only method of getting data is elitist. Or, at the very least, exposes privilege.
I think this goes for computing as a whole. We on HN are probably in the crowd of people who feel completely in control of our machines and are fully capable of harnessing its compute power for nearly any communication or processing task we can imagine. More is better if you're an expert so a lot of our tools and services end up being very complicated and granular.
I think there are two dominant mindsets around how to respond to this problem: A) make services that abstract the technical complexity away from end-users or B) encourage users to become more technical or rely on a technical expert if necessary.
The third option is to simplify functionality down to a clear and simple set of easily understandable interfaces which are explicitly extensible where needed. If every industry had a commitment to doing that, we'd soon end up with a very obvious set of interoperable services with a common communication protocol and the possibility of vendor agnostic tools and services. In fact, I think this was the dream for the web at one point. Maybe we could revisit those ideas.
Not at all. The author makes the assumption that "the developer experience is often poor" when working with APIs. That happens often, but not because APIs are elitist or anything like that, but because they're poorly designed and poorly documented. Otherwise, working with APIs is a bliss, if you're a programmer, it's several orders of magnitude better than working with files. Anyways, APIs are not even incompatible with files. APIs don't just return JSON or XML, any API can have an endpoint that returns a file. And the fuss about authentication/keys doesn't go away with files: if the data is protected, you've still got to provide the credentials, regardless whether the data is coming in the form of a file or a JSON document
There's a lot of things that you do via an API besides downloading batches of data. So if you have an API call for downloading data, should you also have a "download CSV" link powered by that API? Sure—and that's what the article claims. So I'm in agreement so far.
But that's not all that APIs are, or are used for. For everything else, all of their complaints are still valid—bad user experience, authentication is usually a PITA, docs are often poor / non-existent / in a different language. But there isn't an easy solution for those like in the "download batch of data" case. So I think it would make more sense trying to find something that helps those situations, too. Definitely include a download link where possible, but don't stop there.
Or you can just have the world’s simplest API by design possible… An API can just be obvious endpoint documentation made super simple. https://api.corgi.cam/v1/
24 comments
[ 2.9 ms ] story [ 65.1 ms ] threadIt’s always worse when there isn’t an API.
That being said, the best APIs are the ones that have good understandable documentation. And I don’t mean some auto generated bullshit, but documentation that your developer can hand off to your data person and whatever project manager is ordering the information, and they’ll not only understand it, they can use it to tell your developer exactly which Y goes into X.
Beyond that you’ll want a decent test API, and you’ll want workable examples of how to make each call in JS/python/c#/java/php at the very least.
And you’ll probably still want the option for batch dumps via SFTP or whatever.
So no, I don’t think APIs are elitist, I just think most of the people who make them either suck or weren’t given enough resources to do a good job.
I disagree, Swagger is auto generated and I prefer to work with external APIs if they have Swagger documentation which allows me to easily test their API via web browser with two clicks, I don't have to open tools like Insomnia
I like public api's that provide access for non identified clients but they are throttled highly, versus clients who register to access a token.
When building a backend, I lived through the age of custom exporters. It sucked. Having an API and the providing helper calls to do stuff like download the recent month in CSV is way better.
I like having an API that both the UI and users who want to directly integrate use as it’s just simpler.
The lesson may be that just having an API is not enough unless you have a big community or ecosystem building on it (eg, AWS).
Look, I agree you probably should just have a CSV download option for basic use cases. Because it’s easier. Not because it “exposes privilege”
You can download all the data, sliced and diced in various ways, via their download page: https://tatoeba.org/eng/downloads - and also via perma-urls. It's easy as pie. I've written a bunch of scripts to do it.
But then in their FAQ they have ( https://en.wiki.tatoeba.org/articles/show/faq#does-tatoeba-p...? )
> # Does Tatoeba provide an API?
> No, it does not (yet). We unfortunately do not have the proper infrastructure to host a public API[...].
And I'm like, "Nooo what you have is amazing. It's fine!". No need to be ashamed about having downloadable files!
I don't mind an API that allows me to easily request the entire dataset I want to grab with a single unauthenticated call. When this is possible, it's easy to create a download link for less-technical users by hard-coding a query into an href tag. The issue is when an API forces me to make a large number of queries (often tens or hundreds of thousands) to construct a relatively small dataset. Combined with rate-limiting and authentication, the whole thing becomes a nightmare to work with.
Sure, the standard API interface is great if you want to programatically interact with an external database through a custom application. But that design does not lend itself well to accessing public data for the purpose of modelling and data analysis. But, it's not the API persay that's the issue. It's the way that APIs are designed.
With the explanation, if you have a product without an API, I guarantee you have a conceptual gap in the value you provide and why. If your product/data is valuable, users will put up with the most terrible UXs, but if you have the shiniest UX with gaps in the underlying useful data, you've basically got a videogame.
Then you need to look at what elitism is. It's not about requiring skills or physical competence to do something, as that would mean anyone who practised something would be a so-called elitist, which is absurd. Elitism is a way people without actual status affect or pretend to be as a way to convince others without status that they are elevated. Elitism is being a poseur. When you are a member of an actual elite, there is negative value in signalling it to an outsider, the only value is to signal your membership to other insiders. So someone who makes effort to signal their status to an outsider would therefore be an elitist.
Viewed that way, an API is not a signal, it is tool that literally refines the value of your data to that which is truly useful. My next product is starting as an API, and then I'm going to add UX skins to it because if it doesn't attract users, it won't be because of the trendy symbolism in the UX, it will be because it doesn't present the real meaningful data they need.
Please, make more APIs, as value for effort on all sides, it's the best possible solution.
Now, I'm not saying that it's an equal metaphor in any way, but worrying about API's not being accessible enough is only valid if the given consumer is having difficulties using/consuming the specified format. You can't write a spotify client with a csv as input, just like you can't read a book in a language you don't know.
Lots of things require expertise, and conflating prerequisites and elitism seems like an overall loss for effective communication.
I think this goes for computing as a whole. We on HN are probably in the crowd of people who feel completely in control of our machines and are fully capable of harnessing its compute power for nearly any communication or processing task we can imagine. More is better if you're an expert so a lot of our tools and services end up being very complicated and granular.
I think there are two dominant mindsets around how to respond to this problem: A) make services that abstract the technical complexity away from end-users or B) encourage users to become more technical or rely on a technical expert if necessary.
The third option is to simplify functionality down to a clear and simple set of easily understandable interfaces which are explicitly extensible where needed. If every industry had a commitment to doing that, we'd soon end up with a very obvious set of interoperable services with a common communication protocol and the possibility of vendor agnostic tools and services. In fact, I think this was the dream for the web at one point. Maybe we could revisit those ideas.
a button you click to download a csv is an api, too!
But that's not all that APIs are, or are used for. For everything else, all of their complaints are still valid—bad user experience, authentication is usually a PITA, docs are often poor / non-existent / in a different language. But there isn't an easy solution for those like in the "download batch of data" case. So I think it would make more sense trying to find something that helps those situations, too. Definitely include a download link where possible, but don't stop there.