login: hnapi / h!jT2X!M
We're looking at launching our startup next month, and I'd love to launch with a fully functioning API. Since I haven't really got a developer network I was hoping that I could here some of your thoughts. I believe a lot of what I have done is unique (at-least a little) but wouldn't be surprised if someone points me to people doing the same thing.
The API is fully browseable through a browser and follows most of the standard REST API idioms. I know its not technically 100% REST, but the few things I chose to do (verbs other than GET/POST, /v1/ in url) I believe were good decisions - but are still obviously up for debate.
The API can output in HTML/XML/JSON/PHP(serialized)/PY(pickled). You can get each format either with an appropriate "Accept:" header, or file extensions (/v1/client/add.json). Some commands (such as POST /v1/invoice/136891/pdf) will always return a certain content type (in this case a PDF file).
GET requests are used for browsing the API. For instance "GET /v1" will return an index, but whats quite cool is "GET /v1/client/add" will return a form in order to create a client. The form code is available in all the exports. A "POST /v1/client/add" is used to add clients. In order to make testing in a browser simpler, adding "?post" to a URL will treat it as a POST request with the other variables.
a. The API is rather incomplete. I'm quite aware of that, but I believe what is up is enough to relay the style and content of the rest. I do have a couple of small issues (such as repeating fields - invoice lines, etc) but am busy working out plans for those.
b. BASIC AUTH isn't great. I have several other methods planned but for the initial launch it'll have to do.
c. Theres no documentation. I'll get something basic up by the time we launch and improve it from there. I honestly believe the browsable nature should be enough for now though.
d. I only created one user with test data for HN. Hopefully that won't be a problem :)
[if you interested in actual startup request invitation at http://www.snapbill.com and expect a Review my Startup sometime next month :)]