[colpabar]

>Do I not know the latest API design principles yet or why are the examples for a de facto industry standard so lousy?

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

[bruce511]

I agree with your post completely except for the importance of speed.

I would rate documentation above speed in my evaluation of an api. If its not documented I can't use it, regardless of how fast if is - if its documented badly and I can't easily use it, I quickly move on to an alternate offering.

Fast is great, and important, and nice to have, but documentation is a deal breaker.

I could go further and say that docs are even more important than "it works" because without docs my definition of "works" may be different to the authors intent.