OpenAPI cures symptoms, not disease
superface.ai
superface.ai
First, the premise of the article is that Open API is for generating documentation. Our company has never meaningfully used it for that. We do send around API docs in Open API format, but it's maybe 5% of the value we get from Open API. Mostly we use it as a language-agnostic definition that can generate clients and servers for us.
> goes towards fixing something that does not even have to be there
I take it that (in your article, anyway) you mean API documentation?
I'm never not going to need API documentation because it's not just syntax. It also tells me how the vendor's object model works. It tells me the right order to make API calls, how to know my rate limit, and how to choose permissions for my API keys that are as narrow as possible.
I think your product has several premises:
1. Many APIs (like SMS providers) are interchangeable except for their request/response schemas
2. It's painful to create an abstraction around a specific vendor's API client
3. It's painful to switch from one API that does (roughly) the same thing to another
4. Many companies are switching between API vendors regularly (or they want to)
In my experience 0 out of 4 of these premises are true. Some of the simplest services (like transactional SMS and e-mail) are not interchangeable, and as you get to something more complex (like the Hubspot API I was working on with this morning), then it's not even close. You can't swap out Salesforce for Hubspot, for example. Their products compete, but their models are different, and (most importantly) I already have data in one vendor that I can't just instantly migrate to another one.
Most of the time I'd say it's not even worst the effort, but for people who are afraid they'll have to switch API vendors, it's easy to just wrap it with generic method calls and let the implementation details live in one place.
Need to swap it out? Spend 30-60 min building a new class that implements the same wrapper interface and you're done.
In reality, people just don't switch APIs that much, and the major vendors (like Twilio) just keep supporting the exact same API for many years in order to accommodate those people.
Years ago when we had SOAP and XML and lots of messy authentication, I could see there being a reason to use a registry of API abstractions, but nowadays the heterogeneity of REST APIs is a mild enough inconvenience that it's not the worth the price to "fix" it -- the price being losing first-party support from the API vendor and having yet another layer to have to debug.
My bad I was not concrete. What I've meant by "this/that" the entire "find the docs - read the docs - program/generate your client using the docs/OAS - maintain your client forever" when we can have application that will do all this without our intervention.
> I'm never not going to need API documentation because it's not just syntax. It also tells me how the vendor's object model works. It tells me the right order to make API calls, how to know my rate limit, and how to choose permissions for my API keys that are as narrow as possible.
Ideally, you should only need to understand the business logic of the API and not how to achieve it, that part can be figured out by your app.
Self-integration approach does not force you to harmonize the offerings. It just abstract you away from the APIs using the business layer (as you are already doing using you classes).
You might try to harmonize some of the vendors if that is what you like, but that is not the gist. With Some vendors and in certain domains it might make sense - that's why we see domain integrators. With others, it either does not make sense or it is not commercially viable. Either way, you can have your app integrating on the abstraction level without you caring about the technicalities.
The sad truth is that vendors in the first place don't want their offerings to be interchangeable. But that is for another discussion.
Also, it is great to hear that codegen from OAS works for you!
> losing first-party support from the API vendor and having yet another layer to have to debug
1. if your app self-integrates you will not loose that 2. you have this layer already in your hexagonal / clean architecture wrappers, what is worse, everyone is bikeshedding, writing this part over and over