This looks great, but my favourite thing might be the Principles section: > Hydra must be stable. It should never crash > Hydra must be lightweight... never use more than 10 MB of memory > API should be completely transparent > API must not be bloated I think these principles should be the standard to which we all hold our software. Looking forward to testing this out! Edit to say: it would be really great to see som…
I personally think APIs exist to hide complexity. They should make sense, they should be usable, but they need not be transparent.
Let's have a rather contrived example. In SDL, you can call SDL_Init(). That does a lot of things, and what it does differs on windows, linux, and OSX. I absolutely don't want the more transparent API of SDL_Init_Windows_Video(), SDL_Init_Windows_Audio(), SDL_Init_Linux_Video() .... And so on. Realistically, for absolute transparency, you'd just do away with the API and write every line of code SDL currently hides (Reductio ad absurdum I know)
The entire point of having that one SDL_Init() call that's identical on all platforms, even though it does many opaque things underneath (and different things per platforms) is that it's easier to understand and use. The goal of an API is to be usable and useful, nothing else. Transparency can often get in the way of usability.
As for the "bloated" bit. Well, I'd rather be able to do too many things than too few. It's a great goal to have a purely orthogonal (no method may be accomplished with another combination of methods) API, but it should not be done at the expense of usability.
> Nothing should be put into it except what's impossible or impractical to do in pure Lua, and what's extremely common and likely to be used in everyone's configs.
This philosophy would lead to twitter not having a friendship API because the only thing practically every api user does is login and (arguably) tweet, only a few deal with friendships or account settings. It would lead to linux not having a configuration option for running more than one physical CPU or hotswapping ram because the wide majority of people will never use these options.
I'm happy that the author of this software decided to make it simple and it seems to be working here, but in the majority of cases of API design, I'd much rather the API be usable, not transparent, and large, not minimalistic. I'd rather be able to call a method that does some common activity for me which I could technically do myself in a 1000 lines of code than not have such a method because it's "bloat".