Created Draft 1.0 documentation (markdown)

Draft-1.0-documentation.md

@@ -0,0 +1,45 @@
+Stuff that needs to change
+========================== 
+
+1. Drop short status codes.
+2. Response to inherit from HttpResponse.
+  + Becomes a type of standard Django Template Response, with .render() method.
+  + add_header() dropped from View - set headers on the response as with standard Django.
+3. Request to extend from HttpRequest.
+  + self.DATA, self.FILES, self.auth, self.method will become request.DATA, request.FILES, request.method...
+4. Resource.filter_response, Resource.validate_request -> Serializer.serialize, Deserializer.deserialize
+  + Serializer, Deserializer will be decoupled from Resource.
+  + Method names changed to serialize, deserializer - conceptually more obvious.
+  + Views will have `.serializer`, `.deserializer`
+5. View and Resource concepts separated.
+  + Views handle request and response objects, provide `.get()`, `.post()`, `.put()`...
+  + Resources handle instances and filter arguments, provide `.read()`, `.create()`, `.list()`...
+  + Views can no longer return raw objects, must return responses.
+  + Views no longer have optional `model`, `form` properties that automagically create resources,
+    if they use a resource, it must be provided using `.resource`
+6. Drop set_script_prefix munging.
+  + Provide a `reverse` call that extends the standard `reverse`,
+    but can take the current request as an argument if an absolute URL is required.
+7. Hooks throughout for creating .resource, .serializer, .renderer etc... instances inside the View, given the classes.
+8. InstanceMixin needs to disappear.
+
+Stuff that might not be quite perfect, but will do for now
+==========================================================
+
+1. `.get_bound_form` will be on the Deserializer.  Not perfect, and I think there might one day be something like a deserializer/renderer that handles form generation, but it's too tricky to tackle right now, and I don't think it's worth it.
+2. Still not sure if having View.resource, View.serializer, View.renderer etc... be classes rather than instances is necessarily the best way around.  Possibly too complicated to figure out until the basics are throughly sorted out.  Also, it does work OK at the moment.
+
+Stuff that's not quite figured out
+==================================
+
+1. If Serializer/Deserializer is decoupled from Resource, what does a typical API definition end up looking like.  Is it too verbose, and does the conceptual clarity make things more obvious to the end developer.  Will we need to consider a higher level wrapper (doubt it), or having resource/serializer instances on the view, rather than classes on the view?  (Would allow for more concise definitions)
+2. Autodiscover.
+  https://github.com/tomchristie/django-rest-framework/pull/72 is the start of this, need to figure out how that hangs together with the new stuff, and if it's flexible enough to allow various routing styles.  Look to Zachary Voase's Dagny for guidance.
+
+
+What needs to be done
+=====================
+
+1. Get cracking on 1.0 documentation.
+2. Gradually migrate codebase towards 1.0, in way that causes minimal disruption.
+3. Triage and clean up existing tickets.