Django REST framework with admin-style browseable self-documenting API
django-rest-framework.org
django-rest-framework.org
* Piston (https://bitbucket.org/jespern/django-piston/)
* Tastiepie (http://toastdriven.github.com/django-tastypie/)
* django-rest-framework (http://django-rest-framework.org/)
* Web Machine (https://github.com/benoitc/dj-webmachine)
* Dagny (https://github.com/zacharyvoase/dagny)
* Roll your own (surprisingly common since it's not too hard)
I think it's great that there are so many options but it's starting to get bewildering. I think part of the reason for this is how un-restful the default django routing/view technique is. The code samples in the Django documentation don't exactly start beginners down the right track the way other web frameworks do. You can do it the right way, but it requires a fair amount of discipline.
I've been toying with replacing all of my django routing/views with a framework (or at least a pattern) that encourages more restful design.
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.
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.
For our RESTful API, I use this:
REST doesn't mean each of your views is in a class and being GET-only doesn't mean something isn't RESTful. I'm not sure I understand your reasoning.
Even the ones that use POST aren't usually RESTful if it's something like a form submission
It doesn't have to be that way. The path of least resistance is something that the framework determines. In many web-frameworks, the path of least resistance is to do everything (the default web dispatch) in a REST-ful style because that's the way the framework leans.
So what's unRESTful about Django?
My point is that the default routing, the built-in helper functions, and the documentation for beginners all discourage it. For example, the router does not route differently based on the HTTP method. It only takes the URL into account and leaves it to the developer to make a switch based on if the method is GET or POST. This means you're effectively doing some of the routing in the urls.py and some of the routing inside your view.
Several of these REST frameworks above (for example the dagny project I mentioned) change that. I think REST is a good enough design pattern that the framework should lean heavily toward it by default.
My main site is django so I appreciate the flexibility I get from it. I think it should be possible to do non-REST. This is one thing that I struggled with as a new user. I thought Django would lead me down the right path and in my opinion the default routing is weak.
Easy to roll your own. Deceptively hard to do it really simply and really well.
Hence the proliferation of frameworks.
I like a comment by Fielding here: "most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result."
http://www.djangopackages.com/grids/g/api/
At this point (mid-2011) Django-Tastypie is the clear winner by its number of authors, updated codebase, documentation, and overall activity.
(I think tastypie is really good tho, btw)
http://queue.acm.org/detail.cfm?id=1053354
The project page itself says 'self-describing'
I find this kind of features is quite interesting, because API-doc is useful when you need a precise information ("I know there is a function for this, but what's the args order again ?"). When the only doc for a new project I am interested in is javadoc/doxygen, I usually run away.
However, it's much better than no documentation; and having it automatically derived makes it more likely to happen. It's much less work, and how much documentation would we have otherwise? Even if no explicit explanations are added, it's an improvement over nothing.
I think active docs, which you experiment with and see the behaviour as in the django story here, is even better again. (Although, there's little guidance and no explanation in these docs; and I got stack traces when I tried to add something.)
However, the big picture is what is missing - I wonder if there is a way to ease the documentation of this also? That shows the high-level interactions between things. I think part of the problem is that API docs show all the options, but often only 20% are used often, you can get by with even a smaller amount, and get something working with even less. That is, examples of concrete instances of API usage, not all the choices. For example, java.lang.String has a surprising number of methods, but most code doesn't use any of them (most code doesn't manipulate strings).
So, perhaps constraining docs in some way: maybe ranking methods by usage frequency; or designating examples, combining the used subsets of docs into one page. One might generalize this slightly, to show commonly used choices: this would give you the idea that this part is background that's always the same, and these parts are the foreground that changes. i.e. a grammar over the API, of common usage patterns.
This still wouldn't be perfect, but an improvement over purely reference docs; and making it much easier to produce would mean they'd be more of it.
An improvement over this would be game mechanics (I don't mean achievement unlocked BS, but a gradual learning curve, with feedback on how you are doing - puzzles, or active exercises IOW.
Selector().add(path, GET=get_entity, PUT=put_entity, ...)
It's nicer with a mapping file:
/path GET get_entity PUT put_entity
* automatic browsable self-documenting HTML output when you hit the API in a browser [1]
* the fact that django-rest-framework uses as much of Django 1.3's class-based view infrastructure as possible, and so fits better with the way Django works.
[1] example: http://api.django-rest-framework.org/