On Tue, 2009-03-31 at 14:35 -0700, bkonrad wrote: > I was fortunate enough today to have a quick chat with Jacob Kaplan- > Moss about the concept of a generic REST API module for Django. We > spoke about how this has been attempted before and some of the > remaining issues that still require attention. After our chat, I > compiled a problem statement that I believe roughly accommodates the > needs of the Django community. My objective here is to hone these > points and then create a solution proposal for review by the core > committers. Feedback greatly appreciated. > > Problem Statement > > Django needs a generic REST API module.
I actually question that very premise. Django needs to support generic REST precisely by *not* trying to wrap it up as a "module". And I say that as somebody who write REST-based applications almost all the time, because it's simply a nice maintainable architecture style. [...] > > 1. Predictable URI Naming > > A logical, clean URI structure is at the core of any REST API. > Individual items and collections should have standard naming schemes > across all resources. Additionally, URIs should be static to the > greatest extent possible. However, URI's vary infinitely across the complete set of all applications. They need to be consistent within an application, but what you do for a particular application is domain specific. What's the existing problem in Django here? Clean, predictable URI's are already possible. Lots of people already use them. > > 2. Graceful Handling of Complex Resources > > Jacob’s example is a GET method to “/heros/superman”. Such a resource > needs to return a complete set of data on Superman, and this means > being able to aggregate data from multiple resources. Again, already possible with views. What isn't possible here? > > 3. Generic / Pluggable Authentication > > Resource data can be sensitive in nature and needs to be distributed > only to those that have a right to receive it. This permissions > system should be generic in the sense that a resource does not > personally allow / deny access, but instead delegates permission > requests to a generic permissions handler. which permission system is used is up to the application. Django already has the contrib.auth module, which can be used even without cookies (although it requires some different middleware). There's a small gap here in providing documentation and probably some HTTP authentication header handling middleware. > > 4. Flexible Serialization > > Django API consumers will have disparate data format needs, and these > need to be addressed. Formats such as XML, YAML, JSON need to be > considered during implementation. So we already have serialisers that handle all of those for querysets. If you're serialising other things, there are a number of approaches discussed in the various threads here already about GSOC for serialisation. Subclassing the existing serialisers isn't particularly difficult. "Solving" serialisation in general, whatever that means, is a project all on its own (as witnessed by the broad scopes of the proposals already discussed herre). > > 5. Clean Request Handling / Mapping > > Jacob notes that browser limitations make one-to-one mapping of HTTP > methods (GET/POST/PUT/DELETE) to CRUD operations only a piece of the > puzzle. Flexibility is need here to accommodate various consumer > classes. That's not too hard to do already. Again, you're describing a bullet point here, rather than identifying some particular problem in Django or proposing a solution (which is a consistent problem throughout this document), so I'm not quite sure where you're coming from. I have done a fair bit of thinking in this area, trying to work out the *minimum* changes to Django to allow as much flexibility as possible. Particularly based on ideas such as JAX-RS (JSR-311 -- the Java REST API framework) and similar things. I think most of these problems -- dispatching to different handlers for different methods can be solved fairly easily with two small modifications to how URL resolvers (and reversers) are picked up and a couple of decorators. If nothing else happens in the interim, that's something I'll do early in the 1.2 timeframe, as I ran out of time for 1.1. > > 6. Proper Links / Foreign Key Resources > > All resources which contain foreign key fields should be serialized to > contain links to said resources in the form of a URI. One potential > expansion on this concept is adding “deep” or “full” serialization > support, whereby a consumer can request that foreign key references be > “folded” in to the core object. This is open for debate. Indeed it is. General REST design (and, remember, you're claiming to be discussing a generic REST API, not something that provides a way to display models) completely separates the API from the persistent storage. They are orthogonal areas. *Sometimes* there will be a nice mapping, but that's not the general case. > > 7. Scalable Deployment / Low Coupling. > > Jacob makes the good point in his “Worst Practices” document that the > resource usage profile of a heavily used API is nothing like that of > the web app component of a service. Therefore, the API module must be > capable of being run on its own server(s). I can't think of anything in Django prevents this now. Jacob's document points out that the developers shouldn't be stupid and should understand sensible computer software engineering practices, which will remain true pretty much forever. I realise the above is going to read very negatively, but I'm highly skeptical of this proposal, particularly at such a late date when you've already (hopefully!) read all the feedback on other people's proposals and seen what we are after. Primarily, there's no proposal in this proposal. What problems are you trying to fix? How are you proposing to fix them? Secondly, I'm not sure there's a huge problem that is solved by implementing a lot of code in Django here. Most of the bullet points are already possible and fairly easy. There's certainly some ground for extra documentation, probably quite a lot of it, around this area. Something I've been personally addressing in an, as yet incomplete, series of blog posts, for example. However, documentation isn't a Summer of Code project. The areas I think are missing aren't Summer of Code length, either (they're more like Two Weekends of Code stuff.). Don't get me wrong; there are definitely some small pieces of code support needed so that developers can be as generic as they want to be when designing their APIs. However, the whole space isn't conducive to saying "this is the best practice" and forcing something on the users, as REST is an architectural *style*, not an architecture. So, if you're really enthused about this, please provide a lot more details, starting with problem description. You've hopefully carefully studied existing code such as the django-restapi project to understand where the difficulties lie in the generic approach. I genuinely doubt there is a generic set of helpers is possible, since "generic" covers such a broad area. We need to loosen up a few things, such as allowing custom URL resolving and reversing so that it can be done a bit more easily for collections of views. I have an idea of the precise amount of difficulty needed there, since it's something I've looked at a fair bit. It's not a summer's worth. I'd want to see a lot more specifics before I could evaluate a proposal along these lines. Regards, Malcolm --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/django-developers?hl=en -~----------~----~----~----~------~----~------~--~---
