There are so many alternatives because most of them suck.
I've had the misfortune of choosing Piston for a production app. The API broke several times, not to mention the version I'm using which is fairly recent is still having problems rendering the documentation (triggers a weird error and then server requires a restart).
Also, automated documentation is NOT a feature you want, it's just something on which devs waist time - it sounds well in practice, until you discover Sphinx. Sphinx does a better job in a more generic way. I don't get it why people reinvent the wheel.
Django's routing is fine IMHO and you can always write your own magic decorators or classes to add on top and it's not that hard to do.
Django's problem is that it doesn't provide guidance on what goes where and how. Even the standard project structure that's first created by django-admin is fucked-up. This is at first a strength, since you can easily spot extensibility points and as such the learning curve is acceptable, but it quickly becomes a problem. I also think that the main unit of abstraction in Django (the apps) are broken since you care more about resources, even in non-restful projects.
> it sounds well in practice, until you discover Sphinx. Sphinx does a better job in a more generic way.
As someone who started to write our API docs in Sphinx (with an appropriate HTTP extension) but saw this and was about to start using it, your comment may have saved me a few hours of work.
Why do you say that Sphinx is better, though? I found that, to document an API, you can either document the code or the API (HTTP-side). Sphinx can do both, but the useful part (HTTP-side documentation) has to be rewritten from scratch and updated separately (unlike the code docs, which can be generated from the docstrings).
For documenting code, Sphinx has the advantage that you can use it for cool stuff like testing the sample code provided. See here: http://sphinx.pocoo.org/ext/doctest.html
But you won't get away with just docstrings. Good documentation also includes a high-level overview of the API, history of changes, a glossary of terms, etc...
It does have a slight learning curve, but it is very extensible while providing enough out-of-the-box already, and some people have been using it to write entire books.
That's exactly what I use too, it's not perfect but it gets you 95% of the way there. I didn't find it too hard to learn, I just picked up the examples and was on my way to writing the docs within a few minutes.
I've had the misfortune of choosing Piston for a production app. The API broke several times, not to mention the version I'm using which is fairly recent is still having problems rendering the documentation (triggers a weird error and then server requires a restart).
Also, automated documentation is NOT a feature you want, it's just something on which devs waist time - it sounds well in practice, until you discover Sphinx. Sphinx does a better job in a more generic way. I don't get it why people reinvent the wheel.
Django's routing is fine IMHO and you can always write your own magic decorators or classes to add on top and it's not that hard to do.
Django's problem is that it doesn't provide guidance on what goes where and how. Even the standard project structure that's first created by django-admin is fucked-up. This is at first a strength, since you can easily spot extensibility points and as such the learning curve is acceptable, but it quickly becomes a problem. I also think that the main unit of abstraction in Django (the apps) are broken since you care more about resources, even in non-restful projects.