For a library that wraps an HTTP API which is already decently designed and documented, *encapsulation* should *not* be the goal. Provide functions that interpret the headers and response bodies, but keep the HTTP API details in the forefront of the user's mental model.
There's a much bigger rant coming on a more general topic here, about how to write libraries that are designed to be eliminable, not libraries that "capture" a problem by forcing a lot of opinions on the user and obscuring in places that ought to be enlightening.
Designing top-down from porcelain to implementation is one cause for this problem. We can do so much better than that.
And when you don't have that obscurantist encapulation mindset, when you explain and make sense from the ground up, then the high-level API for simple or getting-started usage usually just falls out of what you've built.
If the higher level API is lightweight, and if it combines components that are themselves intelligible, then it is *eliminable*: not only useful as-is, but useful to read the source code of, and inlinable by users when they are ready to dive to the next deeper level.
Unfortunately I think there are backwards emotional incentives here. You feel good when people are *using* your library, not when they decide to stop using it. ... right?
But I believe if you publish a package, and somebody reads it and learns from it and doesn't use it, or if they use it and then later eliminate it, then you've done something greater than just give them a package.
If you solve some problem and you wrap that solution up under a higher-level API, that is essentially a business move. You're capturing the market. You've invented some magic, but rather than encouraging others to use it to build competitors, you're making it your secret sauce.
Aeson contains some "secret sauce" I find sad. There's this hyper-optimized internal function with an FFI implementation
unescapeText :: ByteString -> Either UnicodeException Text
If it were in its own library, it'd probably be a great tool for building a fast aeson competitor.
unescapeText :: ByteString -> Either UnicodeException Text
If it were in its own library, it'd probably be a great tool for building a fast aeson competitor.
Instead, it's buried in an internal module, and it doesn't contain a word of documentation about what it's there for. Why?
Don't just build a library that does X; build a library that does X and also serves as a tutorial for how to build a library that does X.
