This.

We don't need to have all interfaces consistent between each other (although this integration might help), but we need them to be consistent with themselves.

Offloading the integration work to a standard interface or library is good, but don't expect to extract the best of the interaction with it only - because the best is precisely at the margin, what is hard to standardize, at the moment in time you are looking at it.

Although it is GOOD to have interfaces/contracts, industrialized things of course.

But the majority of the proponents of these I've met in the industry are the same people that do not care about or understand (for reasons - valid or not) the lifecycle or the normative quality of what they're doing, with the assumption of deferring it to something/one else.

And, with the comparison with SOAP... REST is a mess, yes. But it is considerably less hard to understand and wrap around than SOAP. And it introduced so many better practices and outcomes in the thinking and design and exposure and usability of APIs.

The problem is that we went backwards in many ways...

REST made it easier to define the API and to understand, but pretty much impossible to autogenerate a client for example.

With a well made SOAP API you can autogenerate client code for it, that is type safe and self-documented almost.

For example after using cxf to autogenerate Java for a given SOAP API I may be able to then write in my app:

  SampleApiRecord record = new SampleApiRecord();

  try {
    record.authenticate(token);
  } catch (AuthenticationException e) {
    // auth failed
  }
  User user = record.getUserData();

This can still be painful to use, but at least REST could've built on top of these concepts

The autogeneration stuff works if you're talking Java to Java (or maybe C#) but for everything else it is a huge pain that's simply not worth it.

I agree with the article in principle but REST is an easier problem to handle especially with multiple languages

This is where documenting the API using OpenAPI / Swagger comes in handy. Then you can use code generation tools.

Why is OpenAPI not used more by those exposing public facing APIs?

I'd say because most of the time, 1) the product is designed iteratively, and not API-first (where a clean spec of the API could be done) but most-obvious/target-usage-first (where hand-made/refined queries are done); 2) and then you patch things on top of it.

You may claim that there's a lack of architecture/thinking into this. There is. Precisely because when you build something new, or something you don't master, you go for it iteratively, instead of deep-thinking it.

And after that, when you have your v1, you can redesign it "properly" with a contract, etc. as a v2.

And here again with the v2, you will be asked to build/integrate some other new stuff. Or usage will evolve in a way you didn't project. So you will end up patching either your API directly, or the contract first.

And reactively, again.

And no, architects won't be involved, because their time is supposed to be best spent doing pre-sales, or proof-of-concepts, or suggestions for v(n+1), rather than mingling with developers or production teams about operational matters. /sad sarcasm

Thank you!

I prefer to eat my own dogfood. That usually solves the problem. I design the API with two strictures: First: Any API I can use, my customers can also use. Second: Everything I design must use the API. No backend magic. No black boxes.

The rest (no pun intended) is just permissions.