This is kinda thin, it reads more like an ad than anything else :/
I mean of course you shouldn't make breaking changes to your API unless you must. Of course if its hard to use its not good enough. These are universal truths that apply to most anything that other people build upon or merely use.
I've spent the last two years making a JavaScript API and I feel like there's so much more real substance they could talk about here. Writing an API is a very interesting process, and its hard, harder than writing a general program or even a language.
You don't just have to consider users needs or a grammar. Instead you have to consider all the things your clients (other programmers) might want to do, and all of the things their users might want to do.
This means you have to be extremely forward thinking, considering all the ways programmers might err while building with your library. When making general programs you have to worry about shooting yourself in the foot. With an API, you have to put forth U.N. Peacekeeping levels of effort to make sure nobody is going to shoot anybody or themselves. (Hopefully with better than U.N. Peacekeeping levels of success!)
> If it’s hard to use, it’s not good enough (meaning you have to use it first)
This can't be stressed enough though. One of the lessons I learned here is that making a large number of sample applications (I'm at 44 little apps and counting for my lib) exposes a vast amount of untold hangups, issues, and wishes. It's incredible the things you demand from your API once you start using it compared to the things you thought you'd want. And they've exposed far more kinks than testing alone could have shown me.
Ah I've rambled a bit. Maybe I should write my own experiences later tonight.
There's always a balance between giving an overview for people who have never done this sort of thing before and writing to the aficionados with the battle scars of having done this a few times. Happy to share more detailed notes here, but as it was the original post was quite long already.
I would very much agree with you - the difficulty in writing APIs well come from the fact that 1) it is challenging to predict how people will use it, so you have to code defensively, make sure it's accessible to beginners and sufficiently powerful for experts. 2) once you've published it, even small tweaks become highly painful, increasingly so as you see success.
Comments
This is kinda thin, it reads more like an ad than anything else :/
I mean of course you shouldn't make breaking changes to your API unless you must. Of course if its hard to use its not good enough. These are universal truths that apply to most anything that other people build upon or merely use.
I've spent the last two years making a JavaScript API and I feel like there's so much more real substance they could talk about here. Writing an API is a very interesting process, and its hard, harder than writing a general program or even a language.
You don't just have to consider users needs or a grammar. Instead you have to consider all the things your clients (other programmers) might want to do, and all of the things their users might want to do.
This means you have to be extremely forward thinking, considering all the ways programmers might err while building with your library. When making general programs you have to worry about shooting yourself in the foot. With an API, you have to put forth U.N. Peacekeeping levels of effort to make sure nobody is going to shoot anybody or themselves. (Hopefully with better than U.N. Peacekeeping levels of success!)
> If it’s hard to use, it’s not good enough (meaning you have to use it first)
This can't be stressed enough though. One of the lessons I learned here is that making a large number of sample applications (I'm at 44 little apps and counting for my lib) exposes a vast amount of untold hangups, issues, and wishes. It's incredible the things you demand from your API once you start using it compared to the things you thought you'd want. And they've exposed far more kinks than testing alone could have shown me.
Ah I've rambled a bit. Maybe I should write my own experiences later tonight.
There's always a balance between giving an overview for people who have never done this sort of thing before and writing to the aficionados with the battle scars of having done this a few times. Happy to share more detailed notes here, but as it was the original post was quite long already.
I would very much agree with you - the difficulty in writing APIs well come from the fact that 1) it is challenging to predict how people will use it, so you have to code defensively, make sure it's accessible to beginners and sufficiently powerful for experts. 2) once you've published it, even small tweaks become highly painful, increasingly so as you see success.
Love the parallels with U.N. Peacekeeping