Hacker News Reader

Comment by mherrmann | Hacker News Reader

I agree with all but this one:

Avoid hiding parameters that could be useful E.g. the API is calling another lower-level one, but it isn't exposing some useful parameters the lower-level API supports

APIs have to be supported for years. Anything they expose can become a serious hindrance for API migration in the future. Best to keep the API as simple as possible at first, then only expand it when it is genuinely necessary.

Another one I would add: Keep the API stable. I'm developing a cross-platform file manager with a Python API [1]. I made some (necessary) changes to the API last week. This broke the work flows of some of my users. They were not pleased.

[1]: https://fman.io

View on HN

Author here. Thanks for the feedback. I wrote this because I've seen too many APIs I couldn't use or had to discard later on because they forgot to expose a lower-level parameter. Yes, supporting additional parameters is a trade-off on stability, but I think it boils down to separating things that change frequently from things that shouldn't change, i.e., having a low-level interface and a high-level interface on the same API. Advanced users that work with internal parameters should know they're on unstable territory. Document that to acknowledge them about the risk. They'll have the flexibility they need knowing about the cost. I guess that if you don't do that, you'll lose users for an API that does.

You don't need to expose each internal parameter or write adapters to everything you use. As suggested by the sibling here, sometimes all you need is to pass down kwargs to the low-level call.

Other API guidelines that suggest a similar approach here:

http://tomasp.net/blog/2015/library-layers/

http://www.thereformedprogrammer.net/what-makes-a-good-softw...

Why not fork the library if you need to modify low level behavior?

For the 1% use cases, expect forks. For 19%, give them options. For 80%, give them good defaults.

Yeah, I also think explicitly exposing each parameter called in a lower level API is a recipe for disaster.

One way to avoid that is to pass down kwargs to the low-level call. `pandas` uses that in their plotting function (passed down the matplotlib call).

But can you decide what is necessary for your library's users?

Yes, they'll let you know. Predicting everything people need is impossible.

And in python, if they really need more they can monkeypatch the world.

Reply on news.ycombinator.com