

Django REST framework with admin-style browseable self-documenting API - jonasvp
http://django-rest-framework.org/

======
po
The main REST framework options for Django seem to be:

* 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.

~~~
bad_user
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.

~~~
StavrosK
> 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).

~~~
bad_user
Well, here's a cool plugin I've been using lately:
<https://github.com/deceze/Sphinx-HTTP-domain>

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.

~~~
StavrosK
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.

------
limist
If you're looking for a REST framework for Django, be sure to see this table:

<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.

~~~
tomchristie
Not sure that's quite true really.

(I think tastypie is really good tho, btw)

------
rams
Do not believe any programmer, manager, or salesperson who claims that code
can be self-documenting or automatically documented. It ain't so. Good
documentation includes background and decision information that cannot be
derived from the code. \- Jef Raskin on self-documenting code

<http://queue.acm.org/detail.cfm?id=1053354>

The project page itself says 'self-describing'

~~~
cdavid
You need both (jacob Kaplan-Moss explained this pretty well:
[http://jacobian.org/writing/great-documentation/what-to-
writ...](http://jacobian.org/writing/great-documentation/what-to-write))

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.

~~~
6ren
As a reference, yes. I agree javadocs are little help for the big picture (or
for the search problem of not knowing the term to look for).

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.

------
rndv
I wish there was something like Selector's named arguments
(<http://lukearno.com/projects/selector/>):

Selector().add(path, GET=get_entity, PUT=put_entity, ...)

It's nicer with a mapping file:

/path GET get_entity PUT put_entity

------
ajessup
What are the strengths/weaknesses of this vs. django-piston?

~~~
shawnwall
another strength is this looks to be actively maintained

~~~
tomchristie
we're working on it hard. :) sprints at djangocon this thurs+fri, so hopefully
will pick up some more contributors and really get things rolling...

------
jtchang
Been looking for alternative frameworks to piston. Will be checking this out.

~~~
Emouri
I've used both piston and django-tastypie in production. Tastypie is delicious
compared to piston. You should check it out.

