I spent some time this afternoon trying out apiary.io – Thanks for the tip @marcwes – really a great piece of software! I built my first relayr draft API in a couple of hours and achieved a higher quality than i would ever expect to at this stage.
Markdown has always been a pretty relaxed way of doing markup. Apiary has backed this with some great engineering to create a really powerful tool for developing APIs in an exploratory manner. You define your API as a ‘BluePrint’ which is a simple markdown file supporting their particular semantics. You can use any text editor to create it, but their web tool is pretty good for learning how to use their Markdown. The GitHub connectivity is also a very nice feature I kept committing as I was working which is a good thing – my only criticism would be that the Javascript prompt for a commit message makes it really easy to be negligent (30% committed with ‘WIP’).
Yaray took a quick look at the test code and felt it would be useful. I’m interested to see what the usage stats teach us as we progress the development.
It’s not quite Documentation Driven Design, but the preview mode gives such fast feedback on how the API looks to a newcomer, that you can’t help but add a little explanation. This is a very good thing… As well as defining what others see, writing extensively, allows you to think through your problems in much greater depth than you would otherwise. When you only have a small team, that is golden!
I’ve not shaken my inherent distrust of significant whitespace, but today it didn’t seem to matter. I took maybe three hours and sketched out a v0.1 API. It’s still rough and will evolve over the next couple of days. I’ll share here, but know there is a lot to do.
watch this space!
A Good Thing Every Day 