Comment by erikpukinskis | Hacker News Reader

Comment by erikpukinskis | Hacker News Reader

Parent Full thread

> They autogenerate all API libraries for golang, which means they're not idiomatic, are convoluted to use, and the documentation is a jungle.

Are idiomatic API libraries really a good thing? If an API is used heavily throughout your application, doesn't that mean it's time to wrap that part of the API in some idiomatic wrapper code that is meaningful in your domain?

Functions are idiomatic in all languages. Personally, I'd rather APIs mostly stick to simple functions, and let the application developer build idioms around them if they like. And if the API call involves a web request, I am happy to just make the HTTP call myself. Half the time you need to understand the interchange format to debug your code anyway. My experience is that wrappers rarely protect you from that.

I guess if your application is 90% calls to an API, and you use a huge range of different functions in that API then you'd want a good, complete library. But how common is that?

You're arguing that it's good to (intentionally) break with common code idioms for certain classes of libraries??

Also, have you actually seen the auto-generated APIs he's referring to?

Here are the Godocs for the BigQuery API: https://godoc.org/google.golang.org/api/bigquery/v2

Here's some example code demonstrating the API's bad habits -- such as deeply nested struct pointers, and Do() methods everywhere: https://github.com/google/google-api-go-client/blob/master/e...

Here's the idiomatic library for bigquery: https://godoc.org/google.golang.org/cloud/bigquery

Thanks for that link, looks like that API was created after I started the project using BigQuery.

It's still labeled "experimental" though, which makes me a bit wary to use it just yet.

That's right. It's production-quality, but the API surface might change.

If you're OK with changing your code sometime in the future, then I'd recommend giving it a try for this or your next project. Changes will likely be minimal.

For a production app, wouldn't you "pin" your dependency to a particular version? I know I wouldn't be allowed to track master in my workplace.

Yes! Please do that.

Use something like git-vendor: https://github.com/brettlangdon/git-vendor

Functions are idiomatic in all languages. Personally, I'd rather APIs mostly stick to simple functions, and let the application developer build idioms around them if they like.

Idiomatic APIs can be a real PITA, especially when you call them from a different language. KISS should reign supreme. (With bad 80's special effects in a made for TV movie filmed at a carnival.) If you leave it up to the client developer to build the idiomatic facade/interface, then the API is simpler, the code is more properly idiomatic in the end, and everyone is happier.

Reply on news.ycombinator.com