OpenAPI cures symptoms, not disease

https://superface.ai/blog/openapi-cures-symptoms

by zdne • 5 years ago

4 4 5 years ago

Vosporos• 5 years ago

I've seen adverts more subtle than this one

zdne2• 5 years ago

Is it that you disagree on the topic? There is nothing subtle about the fact that most of the API tools development goes towards fixing something that does not even have to be there.

smt88• 5 years ago

Wow, I really disagree. I'm exactly your target consumer, too. My company maintains several data aggregation platforms that combined are consumers of ~40 third-party web APIs.

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.

OpenAPI cures symptoms, not disease

Related Stories