Is it, though?

The only argument I see is that an API can be misused. There are ergonomics debates we can have about it, but a user intentionally abusing an API wanting to do something that's completely wrong is hardly indication the API is broken.

That's simply not true.

Thanks for the feedback! Can you elaborate on the parts of the API you felt were brittle?

This quite fundamentally flawed. In many cases, the APIs are the most important and hardest work, and the implementation is arbitrary.

This signals a usability fail in my mind.

I think APIs are not like other specs in this regard. Take, for example, Amazon S3: it has a simple, obvious API that makes guarantees that have completely non-obvious implementation constraints, and no "one true path" toward satisfying them.

I take issue with this. If the single most important step to converting developers to /permanently/ using your API isn't something like scalability, security, performance, or functionality, there is something wrong with this world.

Just because you get more people to succeed in trying your API at the beginning, if it doesn't work for their use case over the long haul they are just going to leave and do something else: the key word is then "permanently".

In comparison, Amazon's APIs are often ludicrously complex. Even if you try to use Amazon's client libraries, they are often ludicrously complex, requiring you to construct object factories to get arguments even for the most common request paths.

But, by and large, Amazon's services don't stop working when you get too much data, have well-thought-out authorization mechanisms, have never become randomly slow as lots of users sign up for the service, and are sufficiently flexible to support many different kinds of tasks.

The fact that the first time I sat down and used Amazon's APIs it took me a while to get them working (and that some APIs from them I still haven't gotten around to learning all the properties of) is then irrelevant: I could tell they would do what I wanted once I figured it out, and I have never been disappointed.

Meanwhile, I've come across tons of random startups, often that have websites that are a "little too Web 2.0" (normally a negative indication for an API provider, btw), whom have APIs (or libraries, or daemons, or services, or programming languages) that are great at first but actually sucked.

(I mostly felt the need to make this comment, btw, due to someone else in this thread seemingly arguing against OAuth because, despite being secure, it made the API sufficiently complex that they could no longer use curl with it: that is the opposite method from how you should be choosing an API.)

Impossible. What will the API serve? A list of horses? Wouldn't work if the user needs a mortgage calculator. There is no choice but to define the front-end first. The question is whether it's defined nebulously or with thought - it's rare for thoughtlessness to be the optimal strategy.

Are idiomatic API libraries really a good thing? If an API is used heavily throughout your application, doesn't that mean it's time to wrap that part of the API in some idiomatic wrapper code that is meaningful in your domain?

Functions are idiomatic in all languages. Personally, I'd rather APIs mostly stick to simple functions, and let the application developer build idioms around them if they like. And if the API call involves a web request, I am happy to just make the HTTP call myself. Half the time you need to understand the interchange format to debug your code anyway. My experience is that wrappers rarely protect you from that.

I guess if your application is 90% calls to an API, and you use a huge range of different functions in that API then you'd want a good, complete library. But how common is that?

I love building APIs. The biggest hurdle I see is that you need two active parties on both ends of the API to convince: There is a user, which needs to be convinced to use the API, and a supplier, which also needs to use the API. And there is no incentive to use the API for one or another.

They don't have public APIs you mean. With a bit of effort you could reverse engineer what their app is doing. The real pain is maintaining it, keeping up with changes. Hence why nobody bothers.

The only purpose of an API is providing mechanical access to functionality.

I've had to create and consume these type of APIs. Demoralized and unproductive has always be the result I've gotten.

Yes.

Swagger/OpenAPI is not really a standard, it's just a way to document an API. JsonAPI [1] is an example of a standard.

I only have a few years of API development under my belt, but something I have learned is that consumers of APIs really don't care about any of the points you listed. No one really cares if your API does not strictly follow ReST principles. They care that it works, that it's fast, and that it's well documented, in that order. Sure, using all the different HTTP verbs feels nice as a developer, but you know what is much simpler for everyone? GET for all reads and POST for all writes.

To be clear, I am not saying that you should give up on following best practices in your APIs. What I am saying is that you should design your APIs to meet your clients' needs, not to satisfy "principles of good API design."

[1]: https://jsonapi.org

Has there ever been such a thing?

> API is going to be nearly impossible for the common person to use

Reading what you are replying to and making an argument against that rather than a hypothetical straw man that GP didn’t imply or mean will get you further.

I don't think so. The pervasiveness of web apps and applications consuming web services means there's a lot of work involving web APIs. This doesn't mean the definition of API was narrowed. It's all about context. If your bread and butter is developing web services, you don't waste time with context-free definitions of your API. You talk about the API and everyone is on the same page.