search

goodybag / magic

The Goodybag API
1 stars 0 forks source link

Api Documentation #82

Open lalitkapoor opened 11 years ago

lalitkapoor commented 11 years ago

We should start documenting our API at some point. This will be helpful to us and others who are not so familiar with the API.

Have the documentation will make it much easier for everyone building products to get going - they don't need to ask API team questions or dig through code.

Here are a few projects that help with documentation:

Feel free to add more to the list - we'll review them at some point and start documenting.

jrf0110 commented 11 years ago

+1 to io-docs. All documentation is done through JSON.

jrf0110 commented 11 years ago

To take a look at io-docs in action, browse klouts apis http://developer.klout.com/iodocs

pfrazee commented 11 years ago

Having just glanced through those options, apiary stands out to me. The DSL looks really intuitive and low-effort. The generated doc designs are just okay, but the doc tools are pretty good.

pfrazee commented 11 years ago

@jrf0110 @lalitkapoor thoughts for/against?

jrf0110 commented 11 years ago

I think apiary looks nice. I'm not a HUGE fan of the DSL but it's probably better than writing everything in straight JSON. Also, Apiary is a three-man team. That's cool.

pfrazee commented 11 years ago

I'm curious, what do you think could be better about the DSL?

jrf0110 commented 11 years ago

Well, obviously my remarks are fairly shallow since I've yet to actually use it, but I think that it's weird that text enclosed with three dashes can be both a comment block and an api title. I don't see any real documentation anywhere either. It doesn't seem like it will maintain its prettiness when you have a shit-ton of endpoints. Of course that's what the front-end is for, but we also have to be able to maintain it.

That being said, I don't think I would be unhappy using it. I'd just need to learn it.

pfrazee commented 11 years ago

Ok, yeah, was just curious