I so appreciate a thoughtful API. Working with a great API feels like using a super power: I'm productive, feeling good about the quality of the code I write, and just happy.
Designing a good API is hard work. Above all it requires data about different things people want to do with the API. The more the better. Such data provides an objective measure of how useful the API is.
I'm often tempted to create internal API's, hoping it will bring productivity and joy to working in part of the code. This is hard when the small group working with the code don't produce enough data to support good API design.
Which isn't to say we should give up on code quality, just that API design might often not be the right approach. When writing code used by a small group of people techniques like data modeling can achieve better results.
Top comments (1)
I felt like this when learning the Vault and Consul APIs. Like, "Wait, that's it? No signed HMAC to download a gigantic, disorganized 4kb blob of text crammed into a single JSON value?" (Looking at you, eDNA.)
I now feel more at home using an API than a CLI. Thanks to a couple guys at HashiCorp.