4 ms·

Django REST framework with admin-style browseable self-documenting API

59 points by jonasvp 15y ago

ajessup 15y ago
What are the strengths/weaknesses of this vs. django-piston?
- j4mie 15y ago
  The main advantages are: * 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/ http://api.django-rest-framework.org/
- shawnwall 15y ago
  another strength is this looks to be actively maintained
  - tomchristie 15y ago
    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 15y ago
Been looking for alternative frameworks to piston. Will be checking this out.
- Emouri 15y ago
  I've used both piston and django-tastypie in production. Tastypie is delicious compared to piston. You should check it out.
rams 15y ago
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 http://queue.acm.org/detail.cfm?id=1053354 The project page itself says 'self-describing'
- cdavid 15y ago
  You need both (jacob Kaplan-Moss explained this pretty well: http://jacobian.org/writing/great-documentation/what-to-write http://jacobian.org/writing/great-documentation/what-to-writ...) 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 15y ago
    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.
po 15y ago
The main REST framework options for Django seem to be: * Piston (https://bitbucket.org/jespern/django-piston/ https://bitbucket.org/jespern/django-piston/) * Tastiepie (http://toastdriven.github.com/django-tastypie/ http://toastdriven.github.com/django-tastypie/) * django-rest-framework (http://django-rest-framework.org/ http://django-rest-framework.org/) * Web Machine (https://github.com/benoitc/dj-webmachine https://github.com/benoitc/dj-webmachine) * Dagny (https://github.com/zacharyvoase/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 15y ago
  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 15y ago
    > 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).
limist 15y ago
If you're looking for a REST framework for Django, be sure to see this table: http://www.djangopackages.com/grids/g/api/ 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 15y ago
  Not sure that's quite true really. (I think tastypie is really good tho, btw)
rndv 15y ago
I wish there was something like Selector's named arguments (http://lukearno.com/projects/selector/ 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

59 points by jonasvp 15y ago

ajessup 15y ago

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

j4mie 15y ago
The main advantages are: * 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/ http://api.django-rest-framework.org/
shawnwall 15y ago
another strength is this looks to be actively maintained
- tomchristie 15y ago
  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 15y ago

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

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

rams 15y ago

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 http://queue.acm.org/detail.cfm?id=1053354 The project page itself says 'self-describing'

cdavid 15y ago
You need both (jacob Kaplan-Moss explained this pretty well: http://jacobian.org/writing/great-documentation/what-to-write http://jacobian.org/writing/great-documentation/what-to-writ...) 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 15y ago
  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.

po 15y ago

The main REST framework options for Django seem to be: * Piston (https://bitbucket.org/jespern/django-piston/ https://bitbucket.org/jespern/django-piston/) * Tastiepie (http://toastdriven.github.com/django-tastypie/ http://toastdriven.github.com/django-tastypie/) * django-rest-framework (http://django-rest-framework.org/ http://django-rest-framework.org/) * Web Machine (https://github.com/benoitc/dj-webmachine https://github.com/benoitc/dj-webmachine) * Dagny (https://github.com/zacharyvoase/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 15y ago
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 15y ago
  > 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).

limist 15y ago

If you're looking for a REST framework for Django, be sure to see this table: http://www.djangopackages.com/grids/g/api/ 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 15y ago
Not sure that's quite true really. (I think tastypie is really good tho, btw)

rndv 15y ago

I wish there was something like Selector's named arguments (http://lukearno.com/projects/selector/ 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