Ask HN: Why do companies typically provide APIs but not clients or specs?

8 pointswhitfieldsdad2y ago11 comments

I've noticed that the bulk of my time as a software developer these days is spent reverse engineering third-party REST APIs that don't already have a publicly available API client or publicly available API specification (e.g. OpenAPI).

Why don't more companies publish either a specification for their API or an API client on a website like GitHub?

For small shops with a few engineers, this makes sense, but for companies that we're paying > $100,000/yr. for access to their APIs, it seems like they should also provide an API client for interacting with it - or at the very least, API documentation.

What are the main barriers preventing more companies from releasing either a specification for their APIs or an API client?

Are APIs easier to reverse engineer these days, and therefore it's not really necessary to release a client or specification?

On the other hand, maybe writing a full-fledged API client is an anti-pattern, since callers could simply implement the functionality that they need rather than implementing all of the functionality that they think that they MIGHT need while still reverse engineering the API?

Ask HN: Why do companies typically provide APIs but not clients or specs?

8 pointswhitfieldsdad2y ago11 comments

Why don't more companies publish either a specification for their API or an API client on a website like GitHub?

What are the main barriers preventing more companies from releasing either a specification for their APIs or an API client?

Are APIs easier to reverse engineer these days, and therefore it's not really necessary to release a client or specification?

11 comments

10 comments · 5 top-level

rattray2y ago· 2 in thread

It's just a ton of work to make a good SDK in every major language.

Something I haven't seen mentioned much on this thread is that the ~top feature people want from SDKs at this point is good static types – so you can get autocomplete, docs-on-hover, etc in your editor. Way better than switching back and forth to the docs and crossing your fingers.

Doing that well means copying every little change into the SDKs (forget about it) or using a generator.

The open-source codegen tools (ie, https://openapi-generator.tech/) are pretty crappy, so you need to either build the SDK yourself fully, or spend a bunch of time wrestling with the generator get it halfway-decent, and then you're still letting your customers/developers down.

Disclaimer, I'm starting a company to make it easy for anyone to ship a great SDK with their REST API: https://stainlessapi.com

whitfieldsdadOP2y ago

Yeah, making a good SDK for every major language would be an absolutely Sisyphean task with negligible returns - it'd be great to have at least one solid reference implementation though.

e.g. a reference implementation in Ruby if they're a Ruby shop, a reference implementation in Java if they're a Java shop, etc.

I wonder if you can generate a "good enough" API client to start out with using say, OpenAPI and then tweak it to suit your needs?

Then again, maybe this is where something like gRPC would really shine compared to REST APIs - I'm not sure, but, it seems like an area that could be improved significantly.

Your startup sounds promising, and hopefully it helps to simplify things!

rattray2y ago

Yeah, the path you're talking about is pretty common actually. Companies handwrite one SDK in the language they're most familiar with, then use OpenAPI-Generator to produce a few others and try to patch up the obviously broken things.

They tend to get quite sick of both hand-maintaining any SDK (even in the language they love), and of dealing with the problems/toil of the openapi generator (or the user complaints of the non-idiomatic code they didn't understand, because it was in a different language).

Still, it's better than nothing, so I applaud those who take on the effort!

Thanks for the kind words – we hope to help bring the well-typed nature of gRPC to REST, without making things more complicated.

mcdonje2y ago· 2 in thread

I can't imagine how or why a company would implement libraries or tools to help their clients consume their data. The API is the interface. Every client is doing something different with it.

I do agree that many companies can design and document their APIs better.

whitfieldsdadOP2y ago

That's fair, and in hindsight, I suppose it is a little silly to try to help customers use your platform as it was meant to be used rather than having them sort of guess how to use it...it'll generate revenue either way...

mcdonje2y ago

Not sure my point came across.

I did say they should document better. Customers shouldn't have to reverse engineer.

But you can't account for how all of your customers are going to use your API. It is the interface.

Like, you mentioned in another comment about a python package as an example of what they could offer. Should they offer Rust, Go, JS, etc., clients as well?

If you buy cement, you don't expect the seller to box in the area where it should be poured. They don't have the blueprints to do that correctly. They're not building your building. The trough on the cement truck is their interface. What you do with it is your job to figure out.

1 more reply

injb2y ago· 1 in thread

I presume you're talking about REST apis? If that's the case then virtually every language has a client built in. That's part of the advantage of using HTTP from the API vendor's point of view.

As far as publishing a spec, I don't know but I'm guessing part of it is a reluctance to commit to anything (which does kind of defeat the purpose of a public API).

whitfieldsdadOP2y ago

Ah, yes - I forgot to mention that I was referring to REST APIs :(

I know that you can send HTTP requests in every language - I was moreso referring to say, a Python package that you could import into your project and use off the shelf without having to write one yourself over the course of weeks to months as you become more familiar with the vendor's API.

I suppose that it makes sense that vendors tend to only provide APIs rather than API clients since one client may use say, Ruby rather than Python...

dandevs2y ago

> Why don't more companies publish either a specification for their API or an API client on a website like GitHub?

Being API-first and caring about the developer experience (DX) is still a new phenomenon. Companies like Twilio and Stripe differentiated in DX. Now there's a whole category of API-first startups like seam.co (API for IoT devices), merge.dev (unified API for 180+ integrations), and stytch.com (API for authentication) who publish API clients in major languages like Node.js, Python, Java, and Go. They also publish their OpenAPI specs in case you use a long-tail language and want to generate a client yourself.

IMO, in the next 5 years, it'll become the norm to offer clients if you have a public REST API.

pesfandiar2y ago

Priorities. And MBAs.

> for companies that we're paying > $100,000/yr. for access to their APIs

Case in point; they didn't need to provide any of that for you to pay. The value is coming from elsewhere, and they didn't think the extra upfront and ongoing cost of providing a client or docs is worth it.

j / k navigate · click thread line to collapse

11 comments

10 comments · 5 top-level

rattray2y ago· 2 in thread

It's just a ton of work to make a good SDK in every major language.

Doing that well means copying every little change into the SDKs (forget about it) or using a generator.

Disclaimer, I'm starting a company to make it easy for anyone to ship a great SDK with their REST API: https://stainlessapi.com

whitfieldsdadOP2y ago

Yeah, making a good SDK for every major language would be an absolutely Sisyphean task with negligible returns - it'd be great to have at least one solid reference implementation though.

e.g. a reference implementation in Ruby if they're a Ruby shop, a reference implementation in Java if they're a Java shop, etc.

I wonder if you can generate a "good enough" API client to start out with using say, OpenAPI and then tweak it to suit your needs?

Then again, maybe this is where something like gRPC would really shine compared to REST APIs - I'm not sure, but, it seems like an area that could be improved significantly.

Your startup sounds promising, and hopefully it helps to simplify things!

rattray2y ago

Still, it's better than nothing, so I applaud those who take on the effort!

Thanks for the kind words – we hope to help bring the well-typed nature of gRPC to REST, without making things more complicated.

mcdonje2y ago· 2 in thread

I can't imagine how or why a company would implement libraries or tools to help their clients consume their data. The API is the interface. Every client is doing something different with it.

I do agree that many companies can design and document their APIs better.

whitfieldsdadOP2y ago

mcdonje2y ago

Not sure my point came across.

I did say they should document better. Customers shouldn't have to reverse engineer.

But you can't account for how all of your customers are going to use your API. It is the interface.

Like, you mentioned in another comment about a python package as an example of what they could offer. Should they offer Rust, Go, JS, etc., clients as well?

1 more reply

injb2y ago· 1 in thread

I presume you're talking about REST apis? If that's the case then virtually every language has a client built in. That's part of the advantage of using HTTP from the API vendor's point of view.

As far as publishing a spec, I don't know but I'm guessing part of it is a reluctance to commit to anything (which does kind of defeat the purpose of a public API).

whitfieldsdadOP2y ago

Ah, yes - I forgot to mention that I was referring to REST APIs :(

I suppose that it makes sense that vendors tend to only provide APIs rather than API clients since one client may use say, Ruby rather than Python...

dandevs2y ago

> Why don't more companies publish either a specification for their API or an API client on a website like GitHub?

IMO, in the next 5 years, it'll become the norm to offer clients if you have a public REST API.

pesfandiar2y ago

Priorities. And MBAs.

> for companies that we're paying > $100,000/yr. for access to their APIs

j / k navigate · click thread line to collapse