4 ms·

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

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 https://fman.io

halflings 9y ago
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).
Scarblac 9y ago
But can you decide what is necessary for your library's users?
- bpicolo 9y ago
  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.
flaviojuvenal 9y ago
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://tomasp.net/blog/2015/library-layers/ http://www.thereformedprogrammer.net/what-makes-a-good-software-library/ http://www.thereformedprogrammer.net/what-makes-a-good-softw...
- spease 9y ago
  Why not fork the library if you need to modify low level behavior?
  - flaviojuvenal 9y ago
    For the 1% use cases, expect forks. For 19%, give them options. For 80%, give them good defaults.

halflings 9y ago

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).

Scarblac 9y ago

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

bpicolo 9y ago
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.

flaviojuvenal 9y ago

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://tomasp.net/blog/2015/library-layers/ http://www.thereformedprogrammer.net/what-makes-a-good-software-library/ http://www.thereformedprogrammer.net/what-makes-a-good-softw...

spease 9y ago
Why not fork the library if you need to modify low level behavior?
- flaviojuvenal 9y ago
  For the 1% use cases, expect forks. For 19%, give them options. For 80%, give them good defaults.