17 Getting to 1.0

Tom Christie edited this page 2013-05-08 01:52:39 -07:00

Table of Contents

• Stuff that needs to change
• Stuff that might not be quite perfect, but will do for now
• Stuff that's not quite figured out
• What needs to be done

This page was the set of design changes that eventually lead to the 2.0 release. - It is left here for historical reasons only .

---

This is a rough attempt at getting the project to a throughly well documented, conceptually clean, and totally kick-ass Web API framework. Right now I think we're something like 70-80% of the way there, a lot of the hard work has been done, but there's still a little way to go before I feel like we could hit a proper 1.0 release.

Please feel free to edit and improve this page.

Stuff that needs to change

1. Drop short status codes. #126 DONE
2. Response to inherit from HttpResponse. #127 DONE

• 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. #128 DONE

• self.DATA, self.FILES, self.auth, self.method will become request.DATA, request.FILES, request.method... Regular attributes on the request (eg. .META etc.) will still be available.

4. Resource.filter_response, Resource.validate_request -> Serializer.serialize, Deserializer.deserialize DONE

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

• 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.
• Resources never deal with anything at HTTP level.
• 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. #167 DONE

• 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. DONE
8. Drop support for unnamed args in URLs filtering as pk. Better to always be explicit in the urlconf. DONE
9. InstanceMixin needs to disappear. DONE
10. .CONTENT probably needs to disappear. To confusing to have that as well as .DATA and .FILES. DONE
11. Explorable JSON: The default JSON output could have a section for placing meta information either by default or by swapping in a new serializer. This is common in REST API's as a place to give clients things such as type information, pagination links, etc... Two approaches seem to make sense: a Tastypie compatible approach ( with a meta dict and objects list) or something like the well-regarded foursquare API (with meta, and response dicts) (@poswald)
12. Support a camelCase serializer to be extra JavaScript-friendly (@poswald)

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. DONE [Yes it was difficult, and yes it will be very worth it - really like how the new serialization API looks]
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.
3. Having the view instance passed to all the pluggable components is a bit hacky really, and it'd be nice to get rid of this. That won't be able to happen until the Request (3) and Response (4) changes above have happened, and even then it's still a bit tricky (eg the Documenting Renderers need to know the view name and description.) May happen before 1.0, may happen after.

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) LOOKS GOOD - See part 3 of the tutorial
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. Designed, but not yet implemented. See part 6 of the tutorial

What needs to be done

1. Get cracking on 1.0 documentation. (Can start on docs, before code is complete)

• Introduction, Getting started.
• API guide.
  • Views.
  • Requests & Responses.
  • Renderers & Parsers.
  • Authentication & Permissions.
  • Serializing & Deserializing.
  • Resources.
• Examples. (Use existing examples.)
• Contributing and other topics.

2. Gradually migrate codebase towards 1.0, in way that causes minimal disruption.
3. Triage and clean up existing tickets.