From deedf6957d14c2808c00a009ac2c1d4528cb80c9 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 1 Sep 2012 20:26:27 +0100 Subject: REST framework 2 docs --- docs/topics/csrf.md | 12 ++++++++++++ docs/topics/formoverloading.md | 43 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) create mode 100644 docs/topics/csrf.md create mode 100644 docs/topics/formoverloading.md (limited to 'docs/topics') diff --git a/docs/topics/csrf.md b/docs/topics/csrf.md new file mode 100644 index 00000000..a2ee1b9c --- /dev/null +++ b/docs/topics/csrf.md @@ -0,0 +1,12 @@ +# Working with AJAX and CSRF + +> "Take a close look at possible CSRF / XSRF vulnerabilities on your own websites. They're the worst kind of vulnerability -- very easy to exploit by attackers, yet not so intuitively easy to understand for software developers, at least until you've been bitten by one." +> +> — [Jeff Atwood][cite] + +* Explain need to add CSRF token to AJAX requests. +* Explain defered CSRF style used by REST framework +* Why you should use Django's standard login/logout views, and not REST framework view + + +[cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html \ No newline at end of file diff --git a/docs/topics/formoverloading.md b/docs/topics/formoverloading.md new file mode 100644 index 00000000..a1828c3b --- /dev/null +++ b/docs/topics/formoverloading.md @@ -0,0 +1,43 @@ +# Browser based PUT & DELETE + +> "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" +> +> — [RESTful Web Services](1), Leonard Richardson & Sam Ruby. + +## Overloading the HTTP method + +**TODO: Preamble.** Note that this is the same strategy as is used in [Ruby on Rails](2). + +For example, given the following form: + + + +`request.method` would return `"DELETE"`. + +## Overloading the HTTP content type + +Browser-based submission of content types other than form are supported by using form fields named `_content` and `_content_type`: + +For example, given the following form: + + + +`request.content_type` would return `"application/json"`, and `request.content` would return `"{'count': 1}"` + +## Why not just use Javascript? + +**[TODO]** + +## Doesn't HTML5 support PUT and DELETE forms? + +Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec](3). There remains [ongoing discussion](4) about adding support for `PUT` and `DELETE`, as well as how to support content-types other than form-encoded data. + +[1]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 +[2]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work +[3]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 +[4]: http://amundsen.com/examples/put-delete-forms/ -- cgit v1.2.3 From 99415564741ca849c0771a3cdd3c18a72b74a373 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 1 Sep 2012 21:23:50 +0100 Subject: Get docs ready to deploy --- docs/topics/credits.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/topics/credits.md (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md new file mode 100644 index 00000000..87b343a0 --- /dev/null +++ b/docs/topics/credits.md @@ -0,0 +1,53 @@ +# Credits + +The following people have helped make REST framework great. + +* Tom Christie \ +* Marko Tibold \ +* Paul Bagwell \ +* Sébastien Piquemal \ +* Carmen Wick \ +* Alex Ehlke \ +* Alen Mujezinovic \ +* Carles Barrobés \ +* Michael Fötsch \ +* David Larlet \ +* Andrew Straw \ +* Zeth \ +* Fernando Zunino \ +* Jens Alm \ +* Craig Blaszczyk \ +* Garcia Solero \ +* Tom Drummond \ +* Danilo Bargen \ +* Andrew McCloud \ +* Thomas Steinacher \ +* Meurig Freeman \ +* Anthony Nemitz \ +* Ewoud Kohl van Wijngaarden \ +* Michael Ding \ +* Mjumbe Poe \ +* Natim \ +* Sebastian Żurek \ +* Benoit C \ +* Chris Pickett \ +* Ben Timby \ +* Michele Lazzeri \ +* Camille Harang \ +* Paul Oswald \ +* Sean C. Farley \ +* Daniel Izquierdo \ +* Can Yavuz \ +* Shawn Lewis \ + +Many thanks to everyone who's contributed to the project. + +## Contact + +To contact the author directly: + +* twitter: [@_tomchristie][twitter] +* mail: [tom@tomchristie.com][email] + +[email]: mailto:tom@tomchristie.com +[twitter]: http://twitter.com/_tomchristie \ No newline at end of file -- cgit v1.2.3 From 73d337ea5dc09bfc8d1ca0c38a39f39f549577eb Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 1 Sep 2012 23:14:48 +0100 Subject: Fix credits doc --- docs/topics/credits.md | 74 +++++++++++++++++++++++++------------------------- 1 file changed, 37 insertions(+), 37 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 87b343a0..e89ec4b1 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -2,43 +2,43 @@ The following people have helped make REST framework great. -* Tom Christie \ -* Marko Tibold \ -* Paul Bagwell \ -* Sébastien Piquemal \ -* Carmen Wick \ -* Alex Ehlke \ -* Alen Mujezinovic \ -* Carles Barrobés \ -* Michael Fötsch \ -* David Larlet \ -* Andrew Straw \ -* Zeth \ -* Fernando Zunino \ -* Jens Alm \ -* Craig Blaszczyk \ -* Garcia Solero \ -* Tom Drummond \ -* Danilo Bargen \ -* Andrew McCloud \ -* Thomas Steinacher \ -* Meurig Freeman \ -* Anthony Nemitz \ -* Ewoud Kohl van Wijngaarden \ -* Michael Ding \ -* Mjumbe Poe \ -* Natim \ -* Sebastian Żurek \ -* Benoit C \ -* Chris Pickett \ -* Ben Timby \ -* Michele Lazzeri \ -* Camille Harang \ -* Paul Oswald \ -* Sean C. Farley \ -* Daniel Izquierdo \ -* Can Yavuz \ -* Shawn Lewis \ +* Tom Christie +* Marko Tibold +* Paul Bagwell +* Sébastien Piquemal +* Carmen Wick +* Alex Ehlke +* Alen Mujezinovic +* Carles Barrobés +* Michael Fötsch +* David Larlet +* Andrew Straw +* Zeth +* Fernando Zunino +* Jens Alm +* Craig Blaszczyk +* Garcia Solero +* Tom Drummond +* Danilo Bargen +* Andrew McCloud +* Thomas Steinacher +* Meurig Freeman +* Anthony Nemitz +* Ewoud Kohl van Wijngaarden +* Michael Ding +* Mjumbe Poe +* Natim +* Sebastian Żurek +* Benoit C +* Chris Pickett +* Ben Timby +* Michele Lazzeri +* Camille Harang +* Paul Oswald +* Sean C. Farley +* Daniel Izquierdo +* Can Yavuz +* Shawn Lewis Many thanks to everyone who's contributed to the project. -- cgit v1.2.3 From c191a46ef050e6cad5b1ada679615b511f5fe69f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 3 Sep 2012 12:19:16 +0100 Subject: Update credits --- docs/topics/credits.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index e89ec4b1..f85b80d2 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -42,6 +42,14 @@ The following people have helped make REST framework great. Many thanks to everyone who's contributed to the project. +## Additional thanks + +The documentation is built with [Bootstrap] and [Markdown]. + +Project hosting is with [GitHub]. + +Continuous integration testing is managed with [Travis CI][travis-ci]. + ## Contact To contact the author directly: @@ -50,4 +58,8 @@ To contact the author directly: * mail: [tom@tomchristie.com][email] [email]: mailto:tom@tomchristie.com -[twitter]: http://twitter.com/_tomchristie \ No newline at end of file +[twitter]: http://twitter.com/_tomchristie +[bootstrap]: http://twitter.github.com/bootstrap/ +[markdown]: http://daringfireball.net/projects/markdown/ +[github]: github.com/tomchristie/django-rest-framework +[travis-ci]: https://secure.travis-ci.org/tomchristie/django-rest-framework \ No newline at end of file -- cgit v1.2.3 From ef5279e97c0aa083d44489cf374fa75c7c8f53b7 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 5 Sep 2012 13:03:55 +0100 Subject: Improve docs --- docs/topics/contributing.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/topics/contributing.md (limited to 'docs/topics') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md new file mode 100644 index 00000000..cbb41f2a --- /dev/null +++ b/docs/topics/contributing.md @@ -0,0 +1,12 @@ +# Contributing to REST framework + +## Accessing settings + +**Describe api_settings** + +## Managing compatibility issues + +**Describe compat module** + +## Running the tests + -- cgit v1.2.3 From 215de9af81007e81def7ee9f9590e0c12dfec272 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 7 Sep 2012 10:17:47 +0100 Subject: Tidy up --- docs/topics/contributing.md | 4 ---- 1 file changed, 4 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index cbb41f2a..8e8b98ac 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -1,9 +1,5 @@ # Contributing to REST framework -## Accessing settings - -**Describe api_settings** - ## Managing compatibility issues **Describe compat module** -- cgit v1.2.3 From 79144919f6194cfb60c2828adce98c0f696b5189 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 8 Sep 2012 08:38:14 +0100 Subject: Added @alecperkins. --- docs/topics/credits.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index f85b80d2..756008a4 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -39,6 +39,7 @@ The following people have helped make REST framework great. * Daniel Izquierdo * Can Yavuz * Shawn Lewis +* Alec Perkins Many thanks to everyone who's contributed to the project. -- cgit v1.2.3 From 382b277dfc74f337d4d74ab100aec031041e42b7 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 8 Sep 2012 08:41:31 +0100 Subject: Link to github accounts in credits --- docs/topics/credits.md | 118 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 78 insertions(+), 40 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 756008a4..c20f5246 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -2,44 +2,44 @@ The following people have helped make REST framework great. -* Tom Christie -* Marko Tibold -* Paul Bagwell -* Sébastien Piquemal -* Carmen Wick -* Alex Ehlke -* Alen Mujezinovic -* Carles Barrobés -* Michael Fötsch -* David Larlet -* Andrew Straw -* Zeth -* Fernando Zunino -* Jens Alm -* Craig Blaszczyk -* Garcia Solero -* Tom Drummond -* Danilo Bargen -* Andrew McCloud -* Thomas Steinacher -* Meurig Freeman -* Anthony Nemitz -* Ewoud Kohl van Wijngaarden -* Michael Ding -* Mjumbe Poe -* Natim -* Sebastian Żurek -* Benoit C -* Chris Pickett -* Ben Timby -* Michele Lazzeri -* Camille Harang -* Paul Oswald -* Sean C. Farley -* Daniel Izquierdo -* Can Yavuz -* Shawn Lewis -* Alec Perkins +* Tom Christie - [tomchristie] +* Marko Tibold - [markotibold] +* Paul Bagwell - [pbgwl] +* Sébastien Piquemal - [sebpiq] +* Carmen Wick - [cwick] +* Alex Ehlke - [aehlke] +* Alen Mujezinovic - [flashingpumpkin] +* Carles Barrobés - [txels] +* Michael Fötsch - [mfoetsch] +* David Larlet - [david] +* Andrew Straw - [astraw] +* Zeth - [zeth] +* Fernando Zunino - [fzunino] +* Jens Alm - [ulmus] +* Craig Blaszczyk - [jakul] +* Garcia Solero - [garciasolero] +* Tom Drummond - [devioustree] +* Danilo Bargen - [gwrtheyrn] +* Andrew McCloud - [amccloud] +* Thomas Steinacher - [thomasst] +* Meurig Freeman - [meurig] +* Anthony Nemitz - [anemitz] +* Ewoud Kohl van Wijngaarden - [ekohl] +* Michael Ding - [yandy] +* Mjumbe Poe - [mjumbewu] +* Natim - [natim] +* Sebastian Żurek - [sebzur] +* Benoit C - [dzen] +* Chris Pickett - [bunchesofdonald] +* Ben Timby - [btimby] +* Michele Lazzeri - [michelelazzeri-nextage] +* Camille Harang - [mammique] +* Paul Oswald - [poswald] +* Sean C. Farley - [scfarley] +* Daniel Izquierdo - [izquierdo] +* Can Yavuz - [tschan] +* Shawn Lewis - [shawnlewis] +* Alec Perkins - [alecperkins] Many thanks to everyone who's contributed to the project. @@ -56,11 +56,49 @@ Continuous integration testing is managed with [Travis CI][travis-ci]. To contact the author directly: * twitter: [@_tomchristie][twitter] -* mail: [tom@tomchristie.com][email] +* email: [tom@tomchristie.com][email] [email]: mailto:tom@tomchristie.com [twitter]: http://twitter.com/_tomchristie [bootstrap]: http://twitter.github.com/bootstrap/ [markdown]: http://daringfireball.net/projects/markdown/ [github]: github.com/tomchristie/django-rest-framework -[travis-ci]: https://secure.travis-ci.org/tomchristie/django-rest-framework \ No newline at end of file +[travis-ci]: https://secure.travis-ci.org/tomchristie/django-rest-framework +[tomchristie]: https://github.com/tomchristie +[markotibold]: https://github.com/markotibold +[pbgwl]: https://github.com/pbgwl +[sebpiq]: https://github.com/sebpiq +[cwick]: https://github.com/cwick +[aehlke]: https://github.com/aehlke +[flashingpumpkin]: https://github.com/flashingpumpkin +[txels]: https://github.com/txels +[mfoetsch]: https://github.com/mfoetsch +[david]: https://github.com/david +[astraw]: https://github.com/astraw +[zeth]: https://github.com/zeth +[fzunino]: https://github.com/fzunino +[ulmus]: https://github.com/ulmus +[jakul]: https://github.com/jakul +[garciasolero]: https://github.com/garciasolero +[devioustree]: https://github.com/devioustree +[gwrtheyrn]: https://github.com/gwrtheyrn +[amccloud]: https://github.com/amccloud +[thomasst]: https://github.com/thomasst +[meurig]: https://github.com/meurig +[anemitz]: https://github.com/anemitz +[ekohl]: https://github.com/ekohl +[yandy]: https://github.com/yandy +[mjumbewu]: https://github.com/mjumbewu +[natim]: https://github.com/natim +[sebzur]: https://github.com/sebzur +[dzen]: https://github.com/dzen +[bunchesofdonald]: https://github.com/bunchesofdonald +[btimby]: https://github.com/btimby +[michelelazzeri-nextage]: https://github.com/michelelazzeri-nextage +[mammique]: https://github.com/mammique +[poswald]: https://github.com/poswald +[scfarley]: https://github.com/scfarley +[izquierdo]: https://github.com/izquierdo +[tschan]: https://github.com/tschan +[shawnlewis]: https://github.com/shawnlewis +[alecperkins]: https://github.com/alecperkins -- cgit v1.2.3 From 60e6bba12b6843b01194b6534fb56129ec0b2140 Mon Sep 17 00:00:00 2001 From: Alec Perkins Date: Sun, 9 Sep 2012 16:46:05 -0400 Subject: Browsable API doc topic --- docs/topics/browsable-api.md | 86 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/topics/browsable-api.md (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md new file mode 100644 index 00000000..6d2d2a37 --- /dev/null +++ b/docs/topics/browsable-api.md @@ -0,0 +1,86 @@ +# Working with the Browsable API + +API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`. + +## URLs + +If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `djangorestframework` package includes a [`reverse`](../api-guide/reverse.md) helper for this purpose. + + +## Formats + +By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using `?format=` in the request, so you can look at the raw JSON response in a browser by adding `?format=json` to the URL. There are helpful extensions for viewing JSON in [Firefox](https://addons.mozilla.org/en-US/firefox/addon/jsonview/) and [Chrome](https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc). + + +## Customizing + +To customize the look-and-feel, create a template called `api.html` and add it to your project, eg: `templates/djangorestframework/api.html`, that extends the `djangorestframework/base.html` template. + +The included browsable API template is built with [Bootstrap (2.1.1)](http://getbootstrap.com), making it easy to customize the look-and-feel. + +### Theme + +To replace the theme wholesale, add a `bootstrap_theme` block to your `api.html` and insert a `link` to the desired Bootstrap theme css file. This will completely replace the included theme. + + {% block bootstrap_theme %} + + {% endblock %} + +A suitable replacement theme can be generated using Bootstrap's [Customize Tool](http://twitter.github.com/bootstrap/customize.html#variables). Also, there are pre-made themes available at [Bootswatch](http://bootswatch.com/), which are even hosted by [Bootstrap CDN](http://www.bootstrapcdn.com/). To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above. + +You can also change the navbar variant, which by default is `navbar-inverse`, using the `bootstrap_navbar_variant` block. The empty `{% block bootstrap_navbar_variant %}{% endblock %}` will use the original Bootstrap navbar style. + +For more specific CSS tweaks, use the `extra_style` block instead. + + +### Blocks + +All of the blocks available in the browsable API base template that can be used in your `api.html`. + +* `blockbots` - `` tag that blocks crawlers +* `bodyclass` - (empty) class attribute for the `` +* `bootstrap_theme` - CSS for the Bootstrap theme +* `bootstrap_navbar_variant` - CSS class for the navbar +* `branding` - section of the navbar, see [Bootstrap components](http://twitter.github.com/bootstrap/components.html#navbar) +* `breadcrumbs` - Links showing resource nesting, allowing the user to go back up the resources. It's recommended to preserve these, but they can be overridden using the breadcrumbs block. +* `extrastyle` - (empty) extra CSS for the page +* `extrahead` - (empty) extra markup for the page `` +* `footer` - Any copyright notices or similar footer materials can go here (by default right-aligned) +* `global_heading` - (empty) Use to insert content below the header but before the breadcrumbs. +* `title` - title of the page +* `userlinks` - This is a list of links on the right of the header, by default containing login/logout links. To add links instead of replace, use {{ block.super }} to preserve the authentication links. + +#### Components + +All of the [Bootstrap components](http://twitter.github.com/bootstrap/components.html) are available. + +##### Tooltips + +The browsable API makes use of the Bootstrap tooltips component. Any element with the `js-tooltip` class and a `title` attribute has that title content displayed in a tooltip on hover after a 1000ms delay. + + +### Advanced Customization + +#### Context + +The context that's available to the template: + +* `allowed_methods` : A list of methods allowed by the resource +* `api_settings` : The API settings +* `available_formats` : A list of formats allowed by the resource +* `breadcrumblist` : The list of links following the chain of nested resources +* `content` : The content of the API response +* `description` : The description of the resource, generated from its docstring +* `name` : The name of the resource +* `post_form` : A form instance for use by the POST form (if allowed) +* `put_form` : A form instance for use by the PUT form (if allowed) +* `request` : The request object +* `response` : The response object +* `version` : The version of Django REST Framework +* `view` : The view handling the request +* `FORMAT_PARAM` : self._FORMAT_QUERY_PARAM +* `METHOD_PARAM` : getattr(self.view, '_METHOD_PARAM', None) + +#### Not using base.html + +For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your site, you can simply choose not to have `api.html` extend `base.html`. Then the page content and capabilities are entirely up to you. \ No newline at end of file -- cgit v1.2.3 From 9684b3fe22d731eb84f67877ab94ee74c8761a01 Mon Sep 17 00:00:00 2001 From: Alec Perkins Date: Sun, 9 Sep 2012 17:07:54 -0400 Subject: Reference-style links. Much cleaner. --- docs/topics/browsable-api.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index 6d2d2a37..ba1984f7 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -4,19 +4,19 @@ API may stand for Application *Programming* Interface, but humans have to be abl ## URLs -If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `djangorestframework` package includes a [`reverse`](../api-guide/reverse.md) helper for this purpose. +If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `djangorestframework` package includes a [`reverse`][drfreverse] helper for this purpose. ## Formats -By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using `?format=` in the request, so you can look at the raw JSON response in a browser by adding `?format=json` to the URL. There are helpful extensions for viewing JSON in [Firefox](https://addons.mozilla.org/en-US/firefox/addon/jsonview/) and [Chrome](https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc). +By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using `?format=` in the request, so you can look at the raw JSON response in a browser by adding `?format=json` to the URL. There are helpful extensions for viewing JSON in [Firefox][ffjsonview] and [Chrome][chromejsonview]. ## Customizing To customize the look-and-feel, create a template called `api.html` and add it to your project, eg: `templates/djangorestframework/api.html`, that extends the `djangorestframework/base.html` template. -The included browsable API template is built with [Bootstrap (2.1.1)](http://getbootstrap.com), making it easy to customize the look-and-feel. +The included browsable API template is built with [Bootstrap (2.1.1)][bootstrap], making it easy to customize the look-and-feel. ### Theme @@ -26,7 +26,7 @@ To replace the theme wholesale, add a `bootstrap_theme` block to your `api.html` {% endblock %} -A suitable replacement theme can be generated using Bootstrap's [Customize Tool](http://twitter.github.com/bootstrap/customize.html#variables). Also, there are pre-made themes available at [Bootswatch](http://bootswatch.com/), which are even hosted by [Bootstrap CDN](http://www.bootstrapcdn.com/). To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above. +A suitable replacement theme can be generated using Bootstrap's [Customize Tool][bcustomize]. Also, there are pre-made themes available at [Bootswatch][bswatch]. To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above. You can also change the navbar variant, which by default is `navbar-inverse`, using the `bootstrap_navbar_variant` block. The empty `{% block bootstrap_navbar_variant %}{% endblock %}` will use the original Bootstrap navbar style. @@ -41,7 +41,7 @@ All of the blocks available in the browsable API base template that can be used * `bodyclass` - (empty) class attribute for the `` * `bootstrap_theme` - CSS for the Bootstrap theme * `bootstrap_navbar_variant` - CSS class for the navbar -* `branding` - section of the navbar, see [Bootstrap components](http://twitter.github.com/bootstrap/components.html#navbar) +* `branding` - section of the navbar, see [Bootstrap components][bcomponentsnav] * `breadcrumbs` - Links showing resource nesting, allowing the user to go back up the resources. It's recommended to preserve these, but they can be overridden using the breadcrumbs block. * `extrastyle` - (empty) extra CSS for the page * `extrahead` - (empty) extra markup for the page `` @@ -52,7 +52,7 @@ All of the blocks available in the browsable API base template that can be used #### Components -All of the [Bootstrap components](http://twitter.github.com/bootstrap/components.html) are available. +All of the [Bootstrap components][bcomponents] are available. ##### Tooltips @@ -83,4 +83,15 @@ The context that's available to the template: #### Not using base.html -For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your site, you can simply choose not to have `api.html` extend `base.html`. Then the page content and capabilities are entirely up to you. \ No newline at end of file +For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your site, you can simply choose not to have `api.html` extend `base.html`. Then the page content and capabilities are entirely up to you. + + +[drfreverse]: ../api-guide/reverse.md +[ffjsonview]: https://addons.mozilla.org/en-US/firefox/addon/jsonview/ +[chromejsonview]: https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc +[bootstrap]: http://getbootstrap.com +[bcustomize]: http://twitter.github.com/bootstrap/customize.html#variables +[bswatch]: http://bootswatch.com/ +[bcomponents]: http://twitter.github.com/bootstrap/components.html +[bcomponentsnav]: http://twitter.github.com/bootstrap/components.html#navbar + -- cgit v1.2.3 From 4cbc53a75d2d30d05f202777d4e1626011c2cb2e Mon Sep 17 00:00:00 2001 From: Alec Perkins Date: Sun, 9 Sep 2012 17:25:34 -0400 Subject: Whoops, forgot to explain these. --- docs/topics/browsable-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index ba1984f7..6f8920bb 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -78,8 +78,8 @@ The context that's available to the template: * `response` : The response object * `version` : The version of Django REST Framework * `view` : The view handling the request -* `FORMAT_PARAM` : self._FORMAT_QUERY_PARAM -* `METHOD_PARAM` : getattr(self.view, '_METHOD_PARAM', None) +* `FORMAT_PARAM` : The view can accept a format override +* `METHOD_PARAM` : The view can accept a method override #### Not using base.html -- cgit v1.2.3 From eb761be9d058dbfb9214f200b941496524dc0ded Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 14 Sep 2012 12:43:14 +0100 Subject: Flesh out resources/routers part of tutorial --- docs/topics/changelog.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/topics/changelog.md (limited to 'docs/topics') diff --git a/docs/topics/changelog.md b/docs/topics/changelog.md new file mode 100644 index 00000000..a4fd39e2 --- /dev/null +++ b/docs/topics/changelog.md @@ -0,0 +1,107 @@ +# Release Notes + +## 2.0.0 + +**TODO:** Explain REST framework 2.0 + +## 0.4.0 + +* Supports Django 1.5. +* Fixes issues with 'HEAD' method. +* Allow views to specify template used by TemplateRenderer +* More consistent error responses +* Some serializer fixes +* Fix internet explorer ajax behaviour +* Minor xml and yaml fixes +* Improve setup (eg use staticfiles, not the defunct ADMIN_MEDIA_PREFIX) +* Sensible absolute URL generation, not using hacky set_script_prefix + +## 0.3.3 + +* Added DjangoModelPermissions class to support `django.contrib.auth` style permissions. +* Use `staticfiles` for css files. + - Easier to override. Won't conflict with customised admin styles (eg grappelli) +* Templates are now nicely namespaced. + - Allows easier overriding. +* Drop implied 'pk' filter if last arg in urlconf is unnamed. + - Too magical. Explict is better than implicit. +* Saner template variable autoescaping. +* Tider setup.py +* Updated for URLObject 2.0 +* Bugfixes: + - Bug with PerUserThrottling when user contains unicode chars. + +## 0.3.2 + +* Bugfixes: + * Fix 403 for POST and PUT from the UI with UserLoggedInAuthentication (#115) + * serialize_model method in serializer.py may cause wrong value (#73) + * Fix Error when clicking OPTIONS button (#146) + * And many other fixes +* Remove short status codes + - Zen of Python: "There should be one-- and preferably only one --obvious way to do it." +* get_name, get_description become methods on the view - makes them overridable. +* Improved model mixin API - Hooks for build_query, get_instance_data, get_model, get_queryset, get_ordering + +## 0.3.1 + +* [not documented] + +## 0.3.0 + +* JSONP Support +* Bugfixes, including support for latest markdown release + +## 0.2.4 + +* Fix broken IsAdminUser permission. +* OPTIONS support. +* XMLParser. +* Drop mentions of Blog, BitBucket. + +## 0.2.3 + +* Fix some throttling bugs. +* ``X-Throttle`` header on throttling. +* Support for nesting resources on related models. + +## 0.2.2 + +* Throttling support complete. + +## 0.2.1 + +* Couple of simple bugfixes over 0.2.0 + +## 0.2.0 + +* Big refactoring changes since 0.1.0, ask on the discussion group if anything isn't clear. + The public API has been massively cleaned up. Expect it to be fairly stable from here on in. + +* ``Resource`` becomes decoupled into ``View`` and ``Resource``, your views should now inherit from ``View``, not ``Resource``. + +* The handler functions on views ``.get() .put() .post()`` etc, no longer have the ``content`` and ``auth`` args. + Use ``self.CONTENT`` inside a view to access the deserialized, validated content. + Use ``self.user`` inside a view to access the authenticated user. + +* ``allowed_methods`` and ``anon_allowed_methods`` are now defunct. if a method is defined, it's available. + The ``permissions`` attribute on a ``View`` is now used to provide generic permissions checking. + Use permission classes such as ``FullAnonAccess``, ``IsAuthenticated`` or ``IsUserOrIsAnonReadOnly`` to set the permissions. + +* The ``authenticators`` class becomes ``authentication``. Class names change to ``Authentication``. + +* The ``emitters`` class becomes ``renderers``. Class names change to ``Renderers``. + +* ``ResponseException`` becomes ``ErrorResponse``. + +* The mixin classes have been nicely refactored, the basic mixins are now ``RequestMixin``, ``ResponseMixin``, ``AuthMixin``, and ``ResourceMixin`` + You can reuse these mixin classes individually without using the ``View`` class. + +## 0.1.1 + +* Final build before pulling in all the refactoring changes for 0.2, in case anyone needs to hang on to 0.1. + +## 0.1.0 + +* Initial release. + -- cgit v1.2.3 From a96211d3d1ba246512af5e32c31726a666c467ac Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 16 Sep 2012 21:48:55 +0100 Subject: Simplify negotiation. Drop MSIE hacks. Etc. --- docs/topics/rest-hypermedia-hateoas.md | 52 ++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/topics/rest-hypermedia-hateoas.md (limited to 'docs/topics') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md new file mode 100644 index 00000000..2bca2ab8 --- /dev/null +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -0,0 +1,52 @@ +> You keep using that word "REST". I do not think it means what you think it means. +> +> — Mike Amundsen, [talking at REST fest 2012][cite]. + +# REST, Hypermedia & HATEOAS + +First off, the disclaimer. The name "Django REST framework" was choosen with a view to making sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". + +If you are serious about designing a Hypermedia APIs, you should look to resources outside of this documentation to help inform your design choices. + +The following fall into the "required reading" category. + +* Fielding's dissertation - [Architectural Styles and +the Design of Network-based Software Architectures][dissertation]. +* Fielding's "[REST APIs must be hypertext-driven][hypertext-driven]" blog post. +* Leonard Richardson & Sam Ruby's [RESTful Web Services][restful-web-services]. +* Mike Amundsen's [Building Hypermedia APIs with HTML5 and Node][building-hypermedia-apis]. +* Steve Klabnik's [Designing Hypermedia APIs][designing-hypermedia-apis]. +* The [Richardson Maturity Model][maturitymodel]. + +For a more thorough background, check out Klabnik's [Hypermedia API reading list][readinglist]. + +# Building Hypermedia APIs with REST framework + +REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. + +### What REST framework *does* provide. + +It is self evident that REST framework makes it possible to build Hypermedia APIs. The browseable API that it offers is built on HTML - the hypermedia language of the web. + +REST framework also includes [serialization] and [parser]/[renderer] components that make it easy to build appropriate media types, [hyperlinked relations][fields] for building well-connected systems, and great support for [content negotiation][conneg]. + +### What REST framework *doesn't* provide. + +What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] by default, or the ability to auto-magically create HATEOAS style APIs. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. + +[cite]: http://vimeo.com/channels/restfest/page:2 +[dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm +[hypertext-driven]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven +[restful-web-services]: +[building-hypermedia-apis]: … +[designing-hypermedia-apis]: http://designinghypermediaapis.com/ +[restisover]: http://blog.steveklabnik.com/posts/2012-02-23-rest-is-over +[readinglist]: http://blog.steveklabnik.com/posts/2012-02-27-hypermedia-api-reading-list +[maturitymodel]: http://martinfowler.com/articles/richardsonMaturityModel.html + +[collection]: http://www.amundsen.com/media-types/collection/ +[serialization]: ../api-guide/serializers.md +[parser]: ../api-guide/parsers.md +[renderer]: ../api-guide/renderers.md +[fields]: ../api-guide/fields.md +[conneg]: ../api-guide/content-negotiation.md \ No newline at end of file -- cgit v1.2.3 From 308677037f1b1f2edbd2527beac8505033c98bdc Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 17 Sep 2012 20:19:45 +0100 Subject: Tweak docs, fix .error_data -> .errors --- docs/topics/rest-hypermedia-hateoas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 2bca2ab8..46a4c9d7 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -1,8 +1,8 @@ +# REST, Hypermedia & HATEOAS + > You keep using that word "REST". I do not think it means what you think it means. > -> — Mike Amundsen, [talking at REST fest 2012][cite]. - -# REST, Hypermedia & HATEOAS +> — Mike Amundsen, [REST fest 2012 keynote][cite]. First off, the disclaimer. The name "Django REST framework" was choosen with a view to making sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". -- cgit v1.2.3 From db13401af0d8c84007b8fcfafda560bef964935b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 19 Sep 2012 17:06:43 +0100 Subject: Added @phobologic. Thanks\! --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index c20f5246..e54fd4bf 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -40,6 +40,7 @@ The following people have helped make REST framework great. * Can Yavuz - [tschan] * Shawn Lewis - [shawnlewis] * Alec Perkins - [alecperkins] +* Michael Barrett - [phobologic] Many thanks to everyone who's contributed to the project. @@ -102,3 +103,4 @@ To contact the author directly: [tschan]: https://github.com/tschan [shawnlewis]: https://github.com/shawnlewis [alecperkins]: https://github.com/alecperkins +[phobologic]: https://github.com/phobologic -- cgit v1.2.3 From 4b691c402707775c3048a90531024f3bc5be6f91 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 20 Sep 2012 13:06:27 +0100 Subject: Change package name: djangorestframework -> rest_framework --- docs/topics/browsable-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index 6f8920bb..ed27752f 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -4,7 +4,7 @@ API may stand for Application *Programming* Interface, but humans have to be abl ## URLs -If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `djangorestframework` package includes a [`reverse`][drfreverse] helper for this purpose. +If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `rest_framework` package includes a [`reverse`][drfreverse] helper for this purpose. ## Formats @@ -14,7 +14,7 @@ By default, the API will return the format specified by the headers, which in th ## Customizing -To customize the look-and-feel, create a template called `api.html` and add it to your project, eg: `templates/djangorestframework/api.html`, that extends the `djangorestframework/base.html` template. +To customize the look-and-feel, create a template called `api.html` and add it to your project, eg: `templates/rest_framework/api.html`, that extends the `rest_framework/base.html` template. The included browsable API template is built with [Bootstrap (2.1.1)][bootstrap], making it easy to customize the look-and-feel. -- cgit v1.2.3 From da1f6df4faed60aded0c38977de53877c1d67258 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 26 Sep 2012 23:07:59 +0200 Subject: Added @LaundroMat. Thanks! --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index e54fd4bf..3111254d 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -41,6 +41,7 @@ The following people have helped make REST framework great. * Shawn Lewis - [shawnlewis] * Alec Perkins - [alecperkins] * Michael Barrett - [phobologic] +* Mathieu Dhondt - [laundromat] Many thanks to everyone who's contributed to the project. @@ -104,3 +105,4 @@ To contact the author directly: [shawnlewis]: https://github.com/shawnlewis [alecperkins]: https://github.com/alecperkins [phobologic]: https://github.com/phobologic +[laundromat]: https://github.com/laundromat \ No newline at end of file -- cgit v1.2.3 From 061cffb67bde746367c3d2a0018d821a50ab7ffc Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 27 Sep 2012 12:49:08 +0100 Subject: Added citation to contributing docs --- docs/topics/contributing.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 8e8b98ac..7fd61c10 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -1,8 +1,15 @@ # Contributing to REST framework +> The world can only really be changed one piece at a time. The art is picking that piece. +> +> — [Tim Berners-Lee][cite] + +## Running the tests + +## Building the docs + ## Managing compatibility issues **Describe compat module** -## Running the tests - +[cite]: http://www.w3.org/People/Berners-Lee/FAQ.html \ No newline at end of file -- cgit v1.2.3 From 8582b18ac4f7258acd559c3deac21cee9ae7727d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 27 Sep 2012 14:29:14 +0200 Subject: Added @cyberj. Thanks! --- docs/topics/credits.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 3111254d..b280dba2 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -42,6 +42,7 @@ The following people have helped make REST framework great. * Alec Perkins - [alecperkins] * Michael Barrett - [phobologic] * Mathieu Dhondt - [laundromat] +* Johan Charpentier - [cyberj] Many thanks to everyone who's contributed to the project. @@ -105,4 +106,5 @@ To contact the author directly: [shawnlewis]: https://github.com/shawnlewis [alecperkins]: https://github.com/alecperkins [phobologic]: https://github.com/phobologic -[laundromat]: https://github.com/laundromat \ No newline at end of file +[laundromat]: https://github.com/laundromat +[cyberj]: https://github.com/cyberj \ No newline at end of file -- cgit v1.2.3 From aeeb68f68a8f5a3deb9f1ad06f11dbbd9a8f1ff6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 28 Sep 2012 10:42:14 +0100 Subject: Added @j4mie, and added projects to 'additional thanks' as appropriate. --- docs/topics/credits.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index b280dba2..8ff05e05 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -43,6 +43,7 @@ The following people have helped make REST framework great. * Michael Barrett - [phobologic] * Mathieu Dhondt - [laundromat] * Johan Charpentier - [cyberj] +* Jamie Matthews - [j4mie] Many thanks to everyone who's contributed to the project. @@ -54,6 +55,10 @@ Project hosting is with [GitHub]. Continuous integration testing is managed with [Travis CI][travis-ci]. +Various inspiration taken from the [Piston], [Tastypie] and [Dagny] projects. + +Development of REST framework 2.0 was sponsored by [DabApps]. + ## Contact To contact the author directly: @@ -67,6 +72,11 @@ To contact the author directly: [markdown]: http://daringfireball.net/projects/markdown/ [github]: github.com/tomchristie/django-rest-framework [travis-ci]: https://secure.travis-ci.org/tomchristie/django-rest-framework +[piston]: https://bitbucket.org/jespern/django-piston +[tastypie]: https://github.com/toastdriven/django-tastypie +[dagny]: https://github.com/zacharyvoase/dagny +[dabapps]: http://lab.dabapps.com + [tomchristie]: https://github.com/tomchristie [markotibold]: https://github.com/markotibold [pbgwl]: https://github.com/pbgwl @@ -107,4 +117,5 @@ To contact the author directly: [alecperkins]: https://github.com/alecperkins [phobologic]: https://github.com/phobologic [laundromat]: https://github.com/laundromat -[cyberj]: https://github.com/cyberj \ No newline at end of file +[cyberj]: https://github.com/cyberj +[j4mie]: https://github.com/j4mie \ No newline at end of file -- cgit v1.2.3 From e7685f3eb5c7d7e8fb1678d673f03688012b00cb Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 2 Oct 2012 15:24:42 +0100 Subject: URL overrides in settings fixed up slightly --- docs/topics/formoverloading.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/formoverloading.md b/docs/topics/formoverloading.md index a1828c3b..96cb1388 100644 --- a/docs/topics/formoverloading.md +++ b/docs/topics/formoverloading.md @@ -1,10 +1,10 @@ -# Browser based PUT & DELETE +# Browser hacks > "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" > > — [RESTful Web Services](1), Leonard Richardson & Sam Ruby. -## Overloading the HTTP method +## Browser based PUT, DELETE, etc... **TODO: Preamble.** Note that this is the same strategy as is used in [Ruby on Rails](2). @@ -16,7 +16,7 @@ For example, given the following form: `request.method` would return `"DELETE"`. -## Overloading the HTTP content type +## Browser based submission of non-form content Browser-based submission of content types other than form are supported by using form fields named `_content` and `_content_type`: @@ -29,13 +29,13 @@ For example, given the following form: `request.content_type` would return `"application/json"`, and `request.content` would return `"{'count': 1}"` -## Why not just use Javascript? +## URL based accept headers -**[TODO]** +## URL based format suffixes ## Doesn't HTML5 support PUT and DELETE forms? -Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec](3). There remains [ongoing discussion](4) about adding support for `PUT` and `DELETE`, as well as how to support content-types other than form-encoded data. +Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec](3). There remains [ongoing discussion](4) about adding support for `PUT` and `DELETE`, as well as how to support content types other than form-encoded data. [1]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 [2]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work -- cgit v1.2.3 From 321d4d030a80b67b0f2e12171beb00b717c02804 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 7 Oct 2012 21:30:06 +0200 Subject: Added @mattbo, @maximilianhurl. Thanks! --- docs/topics/credits.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 8ff05e05..539fa09e 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -44,6 +44,8 @@ The following people have helped make REST framework great. * Mathieu Dhondt - [laundromat] * Johan Charpentier - [cyberj] * Jamie Matthews - [j4mie] +* Mattbo - [mattbo] +* Max Hurl - [maximilianhurl] Many thanks to everyone who's contributed to the project. @@ -118,4 +120,6 @@ To contact the author directly: [phobologic]: https://github.com/phobologic [laundromat]: https://github.com/laundromat [cyberj]: https://github.com/cyberj -[j4mie]: https://github.com/j4mie \ No newline at end of file +[j4mie]: https://github.com/j4mie +[mattbo]: https://github.com/mattbo +[maximilianhurl]: https://github.com/maximilianhurl \ No newline at end of file -- cgit v1.2.3 From f4d4d54e030addf64efe68f387b934262a3c173b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 8 Oct 2012 12:17:43 +0100 Subject: Adding migration and changelog docs --- docs/topics/browserhacks.md | 43 +++++++++++++++++ docs/topics/changelog.md | 8 +++- docs/topics/formoverloading.md | 43 ----------------- docs/topics/migration.md | 85 ++++++++++++++++++++++++++++++++++ docs/topics/rest-hypermedia-hateoas.md | 2 +- 5 files changed, 135 insertions(+), 46 deletions(-) create mode 100644 docs/topics/browserhacks.md delete mode 100644 docs/topics/formoverloading.md create mode 100644 docs/topics/migration.md (limited to 'docs/topics') diff --git a/docs/topics/browserhacks.md b/docs/topics/browserhacks.md new file mode 100644 index 00000000..96cb1388 --- /dev/null +++ b/docs/topics/browserhacks.md @@ -0,0 +1,43 @@ +# Browser hacks + +> "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" +> +> — [RESTful Web Services](1), Leonard Richardson & Sam Ruby. + +## Browser based PUT, DELETE, etc... + +**TODO: Preamble.** Note that this is the same strategy as is used in [Ruby on Rails](2). + +For example, given the following form: + + + +`request.method` would return `"DELETE"`. + +## Browser based submission of non-form content + +Browser-based submission of content types other than form are supported by using form fields named `_content` and `_content_type`: + +For example, given the following form: + + + +`request.content_type` would return `"application/json"`, and `request.content` would return `"{'count': 1}"` + +## URL based accept headers + +## URL based format suffixes + +## Doesn't HTML5 support PUT and DELETE forms? + +Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec](3). There remains [ongoing discussion](4) about adding support for `PUT` and `DELETE`, as well as how to support content types other than form-encoded data. + +[1]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 +[2]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work +[3]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 +[4]: http://amundsen.com/examples/put-delete-forms/ diff --git a/docs/topics/changelog.md b/docs/topics/changelog.md index a4fd39e2..15fb6301 100644 --- a/docs/topics/changelog.md +++ b/docs/topics/changelog.md @@ -1,8 +1,11 @@ -# Release Notes +# Change Log ## 2.0.0 -**TODO:** Explain REST framework 2.0 +* **Fix all of the things.** +* For more information please see the [2.0 migration guide][migration]. + +--- ## 0.4.0 @@ -105,3 +108,4 @@ * Initial release. +[migration]: migration.md \ No newline at end of file diff --git a/docs/topics/formoverloading.md b/docs/topics/formoverloading.md deleted file mode 100644 index 96cb1388..00000000 --- a/docs/topics/formoverloading.md +++ /dev/null @@ -1,43 +0,0 @@ -# Browser hacks - -> "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" -> -> — [RESTful Web Services](1), Leonard Richardson & Sam Ruby. - -## Browser based PUT, DELETE, etc... - -**TODO: Preamble.** Note that this is the same strategy as is used in [Ruby on Rails](2). - -For example, given the following form: - - - -`request.method` would return `"DELETE"`. - -## Browser based submission of non-form content - -Browser-based submission of content types other than form are supported by using form fields named `_content` and `_content_type`: - -For example, given the following form: - - - -`request.content_type` would return `"application/json"`, and `request.content` would return `"{'count': 1}"` - -## URL based accept headers - -## URL based format suffixes - -## Doesn't HTML5 support PUT and DELETE forms? - -Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec](3). There remains [ongoing discussion](4) about adding support for `PUT` and `DELETE`, as well as how to support content types other than form-encoded data. - -[1]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 -[2]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work -[3]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 -[4]: http://amundsen.com/examples/put-delete-forms/ diff --git a/docs/topics/migration.md b/docs/topics/migration.md new file mode 100644 index 00000000..f6a301b8 --- /dev/null +++ b/docs/topics/migration.md @@ -0,0 +1,85 @@ +# 2.0 Migration Guide + +REST framework 2.0 introduces a radical redesign of the core components, and a large number of backwards breaking changes. + +### Serialization redesign. + +REST framework's serialization and deserialization previously used a slightly odd combination of serializers for output, and Django Forms and Model Forms for input. The serialization core has been completely redesigned based on work that was originally intended for Django core. + +2.0's form-like serializers comprehensively address those issues, and are a much more flexible and clean solution to the problems around accepting both form-based and non-form based inputs. + +### Generic views improved. + +When REST framework 0.1 was released the current Django version was 1.2. REST framework included a backport of the Django 1.3's upcoming `View` class, but it didn't take full advantage of the generic view implementations. + +As of 2.0 the generic views in REST framework tie in much more cleanly and obviously with Django's existing codebase, and the mixin architecture is radically simplified. + +### Cleaner request-response cycle. + +REST framework 2.0's request-response cycle is now much less complex. + +* Responses inherit from `SimpleTemplateResponse`, allowing rendering to be delegated to the response, not handled by the view. +* Requests extend the regular `HttpRequest`, allowing authentication and parsing to be delegated to the request, not handled by the view. + +### Renamed attribnutes & classes. + +Various attributes and classes have been renamed in order to fit in better with Django's conventions. + +## Example: Blog Posts API + +Let's take a look at an example from the REST framework 0.4 documentation... + + from djangorestframework.resources import ModelResource + from djangorestframework.reverse import reverse + from blogpost.models import BlogPost, Comment + + + class BlogPostResource(ModelResource): + """ + A Blog Post has a *title* and *content*, and can be associated + with zero or more comments. + """ + model = BlogPost + fields = ('created', 'title', 'slug', 'content', 'url', 'comments') + ordering = ('-created',) + + def url(self, instance): + return reverse('blog-post', + kwargs={'key': instance.key}, + request=self.request) + + def comments(self, instance): + return reverse('comments', + kwargs={'blogpost': instance.key}, + request=self.request) + + + class CommentResource(ModelResource): + """ + A Comment is associated with a given Blog Post and has a + *username* and *comment*, and optionally a *rating*. + """ + model = Comment + fields = ('username', 'comment', 'created', 'rating', 'url', 'blogpost') + ordering = ('-created',) + + def blogpost(self, instance): + return reverse('blog-post', + kwargs={'key': instance.blogpost.key}, + request=self.request) + +There's a bit of a mix of concerns going on there. We've got some information about how the data should be serialized, such as the `fields` attribute, and some information about how it should be retrieved from the database - the `ordering` attribute. + +Let's start to re-write this for REST framework 2.0. + + from rest_framework import serializers + + class BlogPostSerializer(serializers.HyperlinkedModelSerializer): + model = BlogPost + fields = ('created', 'title', 'slug', 'content', 'url', 'comments') + + class CommentSerializer(serializers.HyperlinkedModelSerializer): + model = Comment + fields = ('username', 'comment', 'created', 'rating', 'url', 'blogpost') + + diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 46a4c9d7..3aa1ff5f 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -20,7 +20,7 @@ the Design of Network-based Software Architectures][dissertation]. For a more thorough background, check out Klabnik's [Hypermedia API reading list][readinglist]. -# Building Hypermedia APIs with REST framework +## Building Hypermedia APIs with REST framework REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. -- cgit v1.2.3 From 65f592866c5cd5103e99ed453543807bcbdaa9da Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 8 Oct 2012 17:53:18 +0100 Subject: Fix issue where required fields were not being properly validated. Also make model fields with a default value be not required --- docs/topics/rest-hypermedia-hateoas.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 3aa1ff5f..0e183a49 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -32,7 +32,7 @@ REST framework also includes [serialization] and [parser]/[renderer] components ### What REST framework *doesn't* provide. -What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] by default, or the ability to auto-magically create HATEOAS style APIs. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. +What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create HATEOAS style APIs. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. [cite]: http://vimeo.com/channels/restfest/page:2 [dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm @@ -45,6 +45,7 @@ What REST framework doesn't do is give you is machine readable hypermedia format [maturitymodel]: http://martinfowler.com/articles/richardsonMaturityModel.html [collection]: http://www.amundsen.com/media-types/collection/ +[microformats]: http://microformats.org/wiki/Main_Page [serialization]: ../api-guide/serializers.md [parser]: ../api-guide/parsers.md [renderer]: ../api-guide/renderers.md -- cgit v1.2.3 From 52a2ff8f77dc22a65e6f5780de8183f261472342 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Oct 2012 16:44:49 +0100 Subject: Docs tweaks --- docs/topics/rest-hypermedia-hateoas.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 0e183a49..b58dfcb7 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -4,15 +4,15 @@ > > — Mike Amundsen, [REST fest 2012 keynote][cite]. -First off, the disclaimer. The name "Django REST framework" was choosen with a view to making sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". +First off, the disclaimer. The name "Django REST framework" was choosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". If you are serious about designing a Hypermedia APIs, you should look to resources outside of this documentation to help inform your design choices. The following fall into the "required reading" category. -* Fielding's dissertation - [Architectural Styles and +* Roy Fielding's dissertation - [Architectural Styles and the Design of Network-based Software Architectures][dissertation]. -* Fielding's "[REST APIs must be hypertext-driven][hypertext-driven]" blog post. +* Roy Fielding's "[REST APIs must be hypertext-driven][hypertext-driven]" blog post. * Leonard Richardson & Sam Ruby's [RESTful Web Services][restful-web-services]. * Mike Amundsen's [Building Hypermedia APIs with HTML5 and Node][building-hypermedia-apis]. * Steve Klabnik's [Designing Hypermedia APIs][designing-hypermedia-apis]. @@ -32,7 +32,7 @@ REST framework also includes [serialization] and [parser]/[renderer] components ### What REST framework *doesn't* provide. -What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create HATEOAS style APIs. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. +What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include form descriptions, and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. [cite]: http://vimeo.com/channels/restfest/page:2 [dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm -- cgit v1.2.3 From 7608cf1193fd555f31eb9a3d98c6f258720f8022 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 13 Oct 2012 15:07:43 +0100 Subject: Improve documentation for Requests --- docs/topics/browser-enhancements.md | 43 +++++++++++++++++++++++++++++++++++++ docs/topics/browserhacks.md | 43 ------------------------------------- 2 files changed, 43 insertions(+), 43 deletions(-) create mode 100644 docs/topics/browser-enhancements.md delete mode 100644 docs/topics/browserhacks.md (limited to 'docs/topics') diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md new file mode 100644 index 00000000..d4e128ae --- /dev/null +++ b/docs/topics/browser-enhancements.md @@ -0,0 +1,43 @@ +# Browser enhancements + +> "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" +> +> — [RESTful Web Services](1), Leonard Richardson & Sam Ruby. + +## Browser based PUT, DELETE, etc... + +**TODO: Preamble.** Note that this is the same strategy as is used in [Ruby on Rails](2). + +For example, given the following form: + + + +`request.method` would return `"DELETE"`. + +## Browser based submission of non-form content + +Browser-based submission of content types other than form are supported by using form fields named `_content` and `_content_type`: + +For example, given the following form: + + + +`request.content_type` would return `"application/json"`, and `request.stream` would return `"{'count': 1}"` + +## URL based accept headers + +## URL based format suffixes + +## Doesn't HTML5 support PUT and DELETE forms? + +Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec](3). There remains [ongoing discussion](4) about adding support for `PUT` and `DELETE`, as well as how to support content types other than form-encoded data. + +[1]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 +[2]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work +[3]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 +[4]: http://amundsen.com/examples/put-delete-forms/ diff --git a/docs/topics/browserhacks.md b/docs/topics/browserhacks.md deleted file mode 100644 index 96cb1388..00000000 --- a/docs/topics/browserhacks.md +++ /dev/null @@ -1,43 +0,0 @@ -# Browser hacks - -> "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" -> -> — [RESTful Web Services](1), Leonard Richardson & Sam Ruby. - -## Browser based PUT, DELETE, etc... - -**TODO: Preamble.** Note that this is the same strategy as is used in [Ruby on Rails](2). - -For example, given the following form: - - - -`request.method` would return `"DELETE"`. - -## Browser based submission of non-form content - -Browser-based submission of content types other than form are supported by using form fields named `_content` and `_content_type`: - -For example, given the following form: - - - -`request.content_type` would return `"application/json"`, and `request.content` would return `"{'count': 1}"` - -## URL based accept headers - -## URL based format suffixes - -## Doesn't HTML5 support PUT and DELETE forms? - -Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec](3). There remains [ongoing discussion](4) about adding support for `PUT` and `DELETE`, as well as how to support content types other than form-encoded data. - -[1]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 -[2]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work -[3]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 -[4]: http://amundsen.com/examples/put-delete-forms/ -- cgit v1.2.3 From b3477b3b6c1431a03089d68828c13568d02dc990 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 13 Oct 2012 15:34:38 +0100 Subject: Docs tweaks --- docs/topics/browsable-api.md | 2 +- docs/topics/migration.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index ed27752f..df0eb353 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -1,4 +1,4 @@ -# Working with the Browsable API +# The Browsable API API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`. diff --git a/docs/topics/migration.md b/docs/topics/migration.md index f6a301b8..25fc9074 100644 --- a/docs/topics/migration.md +++ b/docs/topics/migration.md @@ -1,5 +1,9 @@ # 2.0 Migration Guide +> Move fast and break things +> +> — Mark Zuckerberg, [the Hacker Way][cite]. + REST framework 2.0 introduces a radical redesign of the core components, and a large number of backwards breaking changes. ### Serialization redesign. @@ -21,7 +25,7 @@ REST framework 2.0's request-response cycle is now much less complex. * Responses inherit from `SimpleTemplateResponse`, allowing rendering to be delegated to the response, not handled by the view. * Requests extend the regular `HttpRequest`, allowing authentication and parsing to be delegated to the request, not handled by the view. -### Renamed attribnutes & classes. +### Renamed attributes & classes. Various attributes and classes have been renamed in order to fit in better with Django's conventions. @@ -82,4 +86,4 @@ Let's start to re-write this for REST framework 2.0. model = Comment fields = ('username', 'comment', 'created', 'rating', 'url', 'blogpost') - +[cite]: http://www.wired.com/business/2012/02/zuck-letter/ -- cgit v1.2.3 From 7a89d7a770d310f8b72178c561fcd04e6c15e5c4 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 14 Oct 2012 20:46:38 +0100 Subject: Work on docs --- docs/topics/browsable-api.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index df0eb353..9fe82e69 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -1,5 +1,10 @@ # The Browsable API +> It is a profoundly erroneous truism... that we should cultivate the habit of thinking of what we are doing. The precise opposite is the case. Civilization advances by extending the number of important operations which we can perform without thinking about them. +> +> — [Alfred North Whitehead][cite], An Introduction to Mathematics (1911) + + API may stand for Application *Programming* Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the `HTML` format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using `POST`, `PUT`, and `DELETE`. ## URLs @@ -85,7 +90,7 @@ The context that's available to the template: For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your site, you can simply choose not to have `api.html` extend `base.html`. Then the page content and capabilities are entirely up to you. - +[cite]: http://en.wikiquote.org/wiki/Alfred_North_Whitehead [drfreverse]: ../api-guide/reverse.md [ffjsonview]: https://addons.mozilla.org/en-US/firefox/addon/jsonview/ [chromejsonview]: https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc -- cgit v1.2.3 From 9c1fba3483b7e81da0744464dcf23a5f12711de2 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 15 Oct 2012 13:27:50 +0100 Subject: Tweak parsers to take parser_context --- docs/topics/rest-hypermedia-hateoas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index b58dfcb7..dda10eb4 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -24,15 +24,15 @@ For a more thorough background, check out Klabnik's [Hypermedia API reading list REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. -### What REST framework *does* provide. +## What REST framework *does* provide. It is self evident that REST framework makes it possible to build Hypermedia APIs. The browseable API that it offers is built on HTML - the hypermedia language of the web. REST framework also includes [serialization] and [parser]/[renderer] components that make it easy to build appropriate media types, [hyperlinked relations][fields] for building well-connected systems, and great support for [content negotiation][conneg]. -### What REST framework *doesn't* provide. +## What REST framework *doesn't* provide. -What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include form descriptions, and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. +What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. [cite]: http://vimeo.com/channels/restfest/page:2 [dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm -- cgit v1.2.3 From 75ebf895ac3dce4b0e4fbe569fc683e16b788a31 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 17 Oct 2012 11:58:15 +0100 Subject: Added @eofs. Thanks! --- docs/topics/credits.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 539fa09e..3f4b9f0d 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -46,6 +46,7 @@ The following people have helped make REST framework great. * Jamie Matthews - [j4mie] * Mattbo - [mattbo] * Max Hurl - [maximilianhurl] +* Tomi Pajunen - [eofs] Many thanks to everyone who's contributed to the project. @@ -122,4 +123,5 @@ To contact the author directly: [cyberj]: https://github.com/cyberj [j4mie]: https://github.com/j4mie [mattbo]: https://github.com/mattbo -[maximilianhurl]: https://github.com/maximilianhurl \ No newline at end of file +[maximilianhurl]: https://github.com/maximilianhurl +[eofs]: https://github.com/eofs \ No newline at end of file -- cgit v1.2.3 From b5daa40852fb5936e6cddb31ecda5c4b40175cd4 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 17 Oct 2012 13:51:15 +0100 Subject: Docs tweaks --- docs/topics/changelog.md | 111 ------------------------------- docs/topics/release-notes.md | 116 +++++++++++++++++++++++++++++++++ docs/topics/rest-hypermedia-hateoas.md | 4 +- 3 files changed, 118 insertions(+), 113 deletions(-) delete mode 100644 docs/topics/changelog.md create mode 100644 docs/topics/release-notes.md (limited to 'docs/topics') diff --git a/docs/topics/changelog.md b/docs/topics/changelog.md deleted file mode 100644 index 15fb6301..00000000 --- a/docs/topics/changelog.md +++ /dev/null @@ -1,111 +0,0 @@ -# Change Log - -## 2.0.0 - -* **Fix all of the things.** -* For more information please see the [2.0 migration guide][migration]. - ---- - -## 0.4.0 - -* Supports Django 1.5. -* Fixes issues with 'HEAD' method. -* Allow views to specify template used by TemplateRenderer -* More consistent error responses -* Some serializer fixes -* Fix internet explorer ajax behaviour -* Minor xml and yaml fixes -* Improve setup (eg use staticfiles, not the defunct ADMIN_MEDIA_PREFIX) -* Sensible absolute URL generation, not using hacky set_script_prefix - -## 0.3.3 - -* Added DjangoModelPermissions class to support `django.contrib.auth` style permissions. -* Use `staticfiles` for css files. - - Easier to override. Won't conflict with customised admin styles (eg grappelli) -* Templates are now nicely namespaced. - - Allows easier overriding. -* Drop implied 'pk' filter if last arg in urlconf is unnamed. - - Too magical. Explict is better than implicit. -* Saner template variable autoescaping. -* Tider setup.py -* Updated for URLObject 2.0 -* Bugfixes: - - Bug with PerUserThrottling when user contains unicode chars. - -## 0.3.2 - -* Bugfixes: - * Fix 403 for POST and PUT from the UI with UserLoggedInAuthentication (#115) - * serialize_model method in serializer.py may cause wrong value (#73) - * Fix Error when clicking OPTIONS button (#146) - * And many other fixes -* Remove short status codes - - Zen of Python: "There should be one-- and preferably only one --obvious way to do it." -* get_name, get_description become methods on the view - makes them overridable. -* Improved model mixin API - Hooks for build_query, get_instance_data, get_model, get_queryset, get_ordering - -## 0.3.1 - -* [not documented] - -## 0.3.0 - -* JSONP Support -* Bugfixes, including support for latest markdown release - -## 0.2.4 - -* Fix broken IsAdminUser permission. -* OPTIONS support. -* XMLParser. -* Drop mentions of Blog, BitBucket. - -## 0.2.3 - -* Fix some throttling bugs. -* ``X-Throttle`` header on throttling. -* Support for nesting resources on related models. - -## 0.2.2 - -* Throttling support complete. - -## 0.2.1 - -* Couple of simple bugfixes over 0.2.0 - -## 0.2.0 - -* Big refactoring changes since 0.1.0, ask on the discussion group if anything isn't clear. - The public API has been massively cleaned up. Expect it to be fairly stable from here on in. - -* ``Resource`` becomes decoupled into ``View`` and ``Resource``, your views should now inherit from ``View``, not ``Resource``. - -* The handler functions on views ``.get() .put() .post()`` etc, no longer have the ``content`` and ``auth`` args. - Use ``self.CONTENT`` inside a view to access the deserialized, validated content. - Use ``self.user`` inside a view to access the authenticated user. - -* ``allowed_methods`` and ``anon_allowed_methods`` are now defunct. if a method is defined, it's available. - The ``permissions`` attribute on a ``View`` is now used to provide generic permissions checking. - Use permission classes such as ``FullAnonAccess``, ``IsAuthenticated`` or ``IsUserOrIsAnonReadOnly`` to set the permissions. - -* The ``authenticators`` class becomes ``authentication``. Class names change to ``Authentication``. - -* The ``emitters`` class becomes ``renderers``. Class names change to ``Renderers``. - -* ``ResponseException`` becomes ``ErrorResponse``. - -* The mixin classes have been nicely refactored, the basic mixins are now ``RequestMixin``, ``ResponseMixin``, ``AuthMixin``, and ``ResourceMixin`` - You can reuse these mixin classes individually without using the ``View`` class. - -## 0.1.1 - -* Final build before pulling in all the refactoring changes for 0.2, in case anyone needs to hang on to 0.1. - -## 0.1.0 - -* Initial release. - -[migration]: migration.md \ No newline at end of file diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md new file mode 100644 index 00000000..a466f4b1 --- /dev/null +++ b/docs/topics/release-notes.md @@ -0,0 +1,116 @@ +# Release Notes + +> Release Early, Release Often +> +> — Eric S. Raymond, [The Cathedral and the Bazaar][cite]. + +## 2.0.0 + +* **Fix all of the things.** (Well, almost.) +* For more information please see the [2.0 migration guide][migration]. + +--- + +## 0.4.0 + +* Supports Django 1.5. +* Fixes issues with 'HEAD' method. +* Allow views to specify template used by TemplateRenderer +* More consistent error responses +* Some serializer fixes +* Fix internet explorer ajax behaviour +* Minor xml and yaml fixes +* Improve setup (eg use staticfiles, not the defunct ADMIN_MEDIA_PREFIX) +* Sensible absolute URL generation, not using hacky set_script_prefix + +## 0.3.3 + +* Added DjangoModelPermissions class to support `django.contrib.auth` style permissions. +* Use `staticfiles` for css files. + - Easier to override. Won't conflict with customised admin styles (eg grappelli) +* Templates are now nicely namespaced. + - Allows easier overriding. +* Drop implied 'pk' filter if last arg in urlconf is unnamed. + - Too magical. Explict is better than implicit. +* Saner template variable autoescaping. +* Tider setup.py +* Updated for URLObject 2.0 +* Bugfixes: + - Bug with PerUserThrottling when user contains unicode chars. + +## 0.3.2 + +* Bugfixes: + * Fix 403 for POST and PUT from the UI with UserLoggedInAuthentication (#115) + * serialize_model method in serializer.py may cause wrong value (#73) + * Fix Error when clicking OPTIONS button (#146) + * And many other fixes +* Remove short status codes + - Zen of Python: "There should be one-- and preferably only one --obvious way to do it." +* get_name, get_description become methods on the view - makes them overridable. +* Improved model mixin API - Hooks for build_query, get_instance_data, get_model, get_queryset, get_ordering + +## 0.3.1 + +* [not documented] + +## 0.3.0 + +* JSONP Support +* Bugfixes, including support for latest markdown release + +## 0.2.4 + +* Fix broken IsAdminUser permission. +* OPTIONS support. +* XMLParser. +* Drop mentions of Blog, BitBucket. + +## 0.2.3 + +* Fix some throttling bugs. +* ``X-Throttle`` header on throttling. +* Support for nesting resources on related models. + +## 0.2.2 + +* Throttling support complete. + +## 0.2.1 + +* Couple of simple bugfixes over 0.2.0 + +## 0.2.0 + +* Big refactoring changes since 0.1.0, ask on the discussion group if anything isn't clear. + The public API has been massively cleaned up. Expect it to be fairly stable from here on in. + +* ``Resource`` becomes decoupled into ``View`` and ``Resource``, your views should now inherit from ``View``, not ``Resource``. + +* The handler functions on views ``.get() .put() .post()`` etc, no longer have the ``content`` and ``auth`` args. + Use ``self.CONTENT`` inside a view to access the deserialized, validated content. + Use ``self.user`` inside a view to access the authenticated user. + +* ``allowed_methods`` and ``anon_allowed_methods`` are now defunct. if a method is defined, it's available. + The ``permissions`` attribute on a ``View`` is now used to provide generic permissions checking. + Use permission classes such as ``FullAnonAccess``, ``IsAuthenticated`` or ``IsUserOrIsAnonReadOnly`` to set the permissions. + +* The ``authenticators`` class becomes ``authentication``. Class names change to ``Authentication``. + +* The ``emitters`` class becomes ``renderers``. Class names change to ``Renderers``. + +* ``ResponseException`` becomes ``ErrorResponse``. + +* The mixin classes have been nicely refactored, the basic mixins are now ``RequestMixin``, ``ResponseMixin``, ``AuthMixin``, and ``ResourceMixin`` + You can reuse these mixin classes individually without using the ``View`` class. + +## 0.1.1 + +* Final build before pulling in all the refactoring changes for 0.2, in case anyone needs to hang on to 0.1. + +## 0.1.0 + +* Initial release. + +[cite]: http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s04.html +[migration]: migration.md \ No newline at end of file diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index dda10eb4..8b0309b9 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -24,13 +24,13 @@ For a more thorough background, check out Klabnik's [Hypermedia API reading list REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. -## What REST framework *does* provide. +## What REST framework provides. It is self evident that REST framework makes it possible to build Hypermedia APIs. The browseable API that it offers is built on HTML - the hypermedia language of the web. REST framework also includes [serialization] and [parser]/[renderer] components that make it easy to build appropriate media types, [hyperlinked relations][fields] for building well-connected systems, and great support for [content negotiation][conneg]. -## What REST framework *doesn't* provide. +## What REST framework doesn't provide. What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. -- cgit v1.2.3 From 6717d654d0bbfdfca4aaea84a5b4814c4e5f7567 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 17 Oct 2012 21:57:23 +0100 Subject: Added @rdobson. Thanks! --- docs/topics/credits.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 3f4b9f0d..6df99237 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -47,6 +47,7 @@ The following people have helped make REST framework great. * Mattbo - [mattbo] * Max Hurl - [maximilianhurl] * Tomi Pajunen - [eofs] +* Rob Dobson - [rdobson] Many thanks to everyone who's contributed to the project. @@ -124,4 +125,5 @@ To contact the author directly: [j4mie]: https://github.com/j4mie [mattbo]: https://github.com/mattbo [maximilianhurl]: https://github.com/maximilianhurl -[eofs]: https://github.com/eofs \ No newline at end of file +[eofs]: https://github.com/eofs +[rdobson]: https://github.com/rdobson -- cgit v1.2.3 From 71a93930fd4df7a1f5f92c67633b813a26a5e938 Mon Sep 17 00:00:00 2001 From: Marko Tibold Date: Sun, 21 Oct 2012 16:34:07 +0200 Subject: Fixing spelling errors. --- docs/topics/csrf.md | 4 ++-- docs/topics/rest-hypermedia-hateoas.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/csrf.md b/docs/topics/csrf.md index a2ee1b9c..043144c1 100644 --- a/docs/topics/csrf.md +++ b/docs/topics/csrf.md @@ -5,8 +5,8 @@ > — [Jeff Atwood][cite] * Explain need to add CSRF token to AJAX requests. -* Explain defered CSRF style used by REST framework +* Explain deferred CSRF style used by REST framework * Why you should use Django's standard login/logout views, and not REST framework view -[cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html \ No newline at end of file +[cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 8b0309b9..d7646892 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -4,7 +4,7 @@ > > — Mike Amundsen, [REST fest 2012 keynote][cite]. -First off, the disclaimer. The name "Django REST framework" was choosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". +First off, the disclaimer. The name "Django REST framework" was chosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs". If you are serious about designing a Hypermedia APIs, you should look to resources outside of this documentation to help inform your design choices. @@ -22,7 +22,7 @@ For a more thorough background, check out Klabnik's [Hypermedia API reading list ## Building Hypermedia APIs with REST framework -REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. +REST framework is an agnostic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. ## What REST framework provides. @@ -50,4 +50,4 @@ What REST framework doesn't do is give you is machine readable hypermedia format [parser]: ../api-guide/parsers.md [renderer]: ../api-guide/renderers.md [fields]: ../api-guide/fields.md -[conneg]: ../api-guide/content-negotiation.md \ No newline at end of file +[conneg]: ../api-guide/content-negotiation.md -- cgit v1.2.3 From 0aed70dc8b9bf2bf6c6bbd540ffadfae9f74bbaa Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 24 Oct 2012 20:50:45 +0200 Subject: Added @diviei - Thanks! --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 6df99237..27a56326 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -48,6 +48,7 @@ The following people have helped make REST framework great. * Max Hurl - [maximilianhurl] * Tomi Pajunen - [eofs] * Rob Dobson - [rdobson] +* Daniel Vaca Araujo - [diviei] Many thanks to everyone who's contributed to the project. @@ -127,3 +128,4 @@ To contact the author directly: [maximilianhurl]: https://github.com/maximilianhurl [eofs]: https://github.com/eofs [rdobson]: https://github.com/rdobson +[diviei]: https://github.com/diviei -- cgit v1.2.3 From cef379db065711bd2f1b0805d28a56f7a80cef37 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 27 Oct 2012 18:39:17 +0100 Subject: 2.0 Announcement --- docs/topics/rest-framework-2-announcement.md | 88 ++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/topics/rest-framework-2-announcement.md (limited to 'docs/topics') diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md new file mode 100644 index 00000000..98e66228 --- /dev/null +++ b/docs/topics/rest-framework-2-announcement.md @@ -0,0 +1,88 @@ +# Django REST framework 2 + +What it is, and why you should care + +> Most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. +> +> — [Roy Fielding][cite] + +REST framework 2 is an almost complete reworking of the original framework, which comprehensivly addresses some of the original design issues. + +Because the latest version should be considered a re-release, rather than an incremental improvement, we've skipped a version, and called this release Django REST framework 2.0. + +This article is intended to give you a flavor of what REST framework 2 is, and why you might want to give it a try. + +## User feedback + +Before we get cracking, let's start with the hard sell, with a few bits of feedback from some early adopters… + +"Django REST framework 2 is beautiful. Some of the API design is worthy of @kennethreitz." - [Kit La Touche][quote1] + +"Since it's pretty much just Django, controlling things like URLs has been a breeze... I think [REST framework 2] has definitely got the right approach here; even simple things like being able to override a function called post to do custom work during rather than having to intimately know what happens during a post make a huge difference to your productivity." - [Ian Strachan][quote2] + +"I switched to the 2.0 branch and I don't regret it - fully refactored my code in another ½ day and it's *much* more to my tastes" - [Bruno Desthuilliers][quote3] + +Sounds good, right? Let's get into some details... + +## Serialization + +REST framework 2 includes a totally re-worked serialization engine, that was initially intended as a replacement for Django's existing inflexible fixture serialization, and which meets the following design goals: + +* A declarative serialization API, that mirrors Django's `Forms`/`ModelForms` API. +* Structural concerns are decoupled from encoding concerns. +* Able to support rendering and parsing to many formats, including both machine-readable representations and HTML forms. +* Validation that can be mapped to obvious and comprehensive error responses. +* Serializers that support both nested, flat, and partially-nested representations. +* Relationships that can be expressed as primary keys, hyperlinks, slug fields, and other custom representations. + +Mapping between the internal state of the system and external representations of that state is the core concern of building Web APIs. Designing serializers that allow the developer to do so in a flexible and obvious way is a deceptively difficult design task, and with the new serialization API we think we've pretty much nailed it. + +## Generic views + +When REST framework was initially released at the start of 2011, the current Django release was version 1.2. REST framework included a backport of Django 1.3's upcoming `View` class, but it didn't take full advantage of the generic view implementations. + +With the new release the generic views in REST framework now tie in with Django's generic views. The end result is that framework is clean, lightweight and easy to use. + +## Requests, Responses & Views + +REST framework 2 includes `Request` and `Response` classes, than are used in place of Django's existing `HttpRequest` and `HttpResponse` classes. Doing so allows logic such as parsing the incoming request or rendering the outgoing response to be supported transparently by the framework. + +The `Request`/`Response` approach leads to a much cleaner API, less logic in the view itself, and a simple, obvious request-response cycle. + +REST framework 2 also allows you to work with both function-based and class-based views. For simple API views all you need is a single `@api_view` decorator, and you're good to go. + + +## API Design + +Pretty much every aspect of REST framework has been reworked, with the aim of ironing out some of the design flaws of the previous versions. Each of the components of REST framework are cleanly decoupled, and can be used independantly of each-other, and there are no monolithic resource classes, overcomplicated mixin combinations, or opinionated serialization or URL routing decisions. + +## Documentation + +As you can see the documentation for REST framework has been radically improved. It gets a completely new style, using markdown for the documentation source, and a bootstrap-based theme for the styling. + +In the author's opinion, using `markdown` for documentation is a much better option that `rst`. It is intuitive and readable, and there is great tooling available, such as the [Mou][mou] editor for Mac OS X, which makes it easy and plesant to work. + +We're really pleased with how the docs style looks - it's simple and clean, and the docs build much more quickly than with the previous sphinx setup. We'll miss being able to use the wonderful [Read the Docs][readthedocs] service, but we think it's a trade-off worth making. + +Developing REST framework's documentation builder into a fully-fledged reusable project is something that we have planned for a future date. + +## The Browseable API + +Django REST framework's most unique feature is the way it is able to serve up both machine-readable representations, and a fully browsable HTML representation to the same endpoints. + +Browseable Web APIs are easier to work with, visualize and debug, and generally makes it easier and more frictionless to inspect and work with. + +With REST framework 2, the browseable API gets a snazzy new bootstrap-based theme that looks great and is even nicer to work with. + +There are also some functionality improvments - actions such as as `POST` and `DELETE` will only display if the user has the appropriate permissions. + +## Summary + +In short, we've engineered the hell outta this thing, and we're incredibly proud of the result. + +[cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-724 +[quote1]: https://twitter.com/kobutsu/status/261689665952833536 +[quote2]: https://groups.google.com/d/msg/django-rest-framework/heRGHzG6BWQ/ooVURgpwVC0J +[quote3]: https://groups.google.com/d/msg/django-rest-framework/flsXbvYqRoY/9lSyntOf5cUJ +[mou]: http://mouapp.com/ +[readthedocs]: https://readthedocs.org/ -- cgit v1.2.3 From 51a64019260d99e3c615b407353e344cf615da1e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 27 Oct 2012 18:47:17 +0100 Subject: Added @madisvain. Thanks! --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 27a56326..a317afde 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -49,6 +49,7 @@ The following people have helped make REST framework great. * Tomi Pajunen - [eofs] * Rob Dobson - [rdobson] * Daniel Vaca Araujo - [diviei] +* Madis Väin - [madisvain] Many thanks to everyone who's contributed to the project. @@ -129,3 +130,4 @@ To contact the author directly: [eofs]: https://github.com/eofs [rdobson]: https://github.com/rdobson [diviei]: https://github.com/diviei +[madisvain]: https://github.com/madisvain -- cgit v1.2.3 From 0c71b4c10095f8783f205fc134a475c04a27f01b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 28 Oct 2012 21:16:04 +0000 Subject: Tweaks --- docs/topics/rest-framework-2-announcement.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md index 98e66228..82e8fe36 100644 --- a/docs/topics/rest-framework-2-announcement.md +++ b/docs/topics/rest-framework-2-announcement.md @@ -56,16 +56,6 @@ REST framework 2 also allows you to work with both function-based and class-base Pretty much every aspect of REST framework has been reworked, with the aim of ironing out some of the design flaws of the previous versions. Each of the components of REST framework are cleanly decoupled, and can be used independantly of each-other, and there are no monolithic resource classes, overcomplicated mixin combinations, or opinionated serialization or URL routing decisions. -## Documentation - -As you can see the documentation for REST framework has been radically improved. It gets a completely new style, using markdown for the documentation source, and a bootstrap-based theme for the styling. - -In the author's opinion, using `markdown` for documentation is a much better option that `rst`. It is intuitive and readable, and there is great tooling available, such as the [Mou][mou] editor for Mac OS X, which makes it easy and plesant to work. - -We're really pleased with how the docs style looks - it's simple and clean, and the docs build much more quickly than with the previous sphinx setup. We'll miss being able to use the wonderful [Read the Docs][readthedocs] service, but we think it's a trade-off worth making. - -Developing REST framework's documentation builder into a fully-fledged reusable project is something that we have planned for a future date. - ## The Browseable API Django REST framework's most unique feature is the way it is able to serve up both machine-readable representations, and a fully browsable HTML representation to the same endpoints. @@ -76,6 +66,16 @@ With REST framework 2, the browseable API gets a snazzy new bootstrap-based them There are also some functionality improvments - actions such as as `POST` and `DELETE` will only display if the user has the appropriate permissions. +![Browseable API][image] + +**Image above**: An example of the browseable API in REST framework 2 + +## Documentation + +As you can see the documentation for REST framework has been radically improved. It gets a completely new style, using markdown for the documentation source, and a bootstrap-based theme for the styling. + +We're really pleased with how the docs style looks - it's simple and clean, is easy to navigate around, and we think it reads great. We'll miss being able to use the wonderful [Read the Docs][readthedocs] service, but we think it's a trade-off worth making. + ## Summary In short, we've engineered the hell outta this thing, and we're incredibly proud of the result. @@ -84,5 +84,5 @@ In short, we've engineered the hell outta this thing, and we're incredibly proud [quote1]: https://twitter.com/kobutsu/status/261689665952833536 [quote2]: https://groups.google.com/d/msg/django-rest-framework/heRGHzG6BWQ/ooVURgpwVC0J [quote3]: https://groups.google.com/d/msg/django-rest-framework/flsXbvYqRoY/9lSyntOf5cUJ -[mou]: http://mouapp.com/ +[image]: ../img/quickstart.png [readthedocs]: https://readthedocs.org/ -- cgit v1.2.3 From 076ca51d6f1e8e22c74810bfcfef76e108cbce77 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 29 Oct 2012 08:53:12 +0000 Subject: Added @minddust. Thanks! --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index a317afde..3b430e42 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -50,6 +50,7 @@ The following people have helped make REST framework great. * Rob Dobson - [rdobson] * Daniel Vaca Araujo - [diviei] * Madis Väin - [madisvain] +* Stephan Groß - [minddust] Many thanks to everyone who's contributed to the project. @@ -131,3 +132,4 @@ To contact the author directly: [rdobson]: https://github.com/rdobson [diviei]: https://github.com/diviei [madisvain]: https://github.com/madisvain +[minddust]: https://github.com/minddust \ No newline at end of file -- cgit v1.2.3 From cf77fd6964c9f226a7c3f6dc5ec9d74a76cc1ab6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 29 Oct 2012 09:10:04 +0000 Subject: Tweak --- docs/topics/rest-framework-2-announcement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md index 82e8fe36..7b97af73 100644 --- a/docs/topics/rest-framework-2-announcement.md +++ b/docs/topics/rest-framework-2-announcement.md @@ -74,7 +74,7 @@ There are also some functionality improvments - actions such as as `POST` and `D As you can see the documentation for REST framework has been radically improved. It gets a completely new style, using markdown for the documentation source, and a bootstrap-based theme for the styling. -We're really pleased with how the docs style looks - it's simple and clean, is easy to navigate around, and we think it reads great. We'll miss being able to use the wonderful [Read the Docs][readthedocs] service, but we think it's a trade-off worth making. +We're really pleased with how the docs style looks - it's simple and clean, is easy to navigate around, and we think it reads great. ## Summary -- cgit v1.2.3 From 5f0d4ef2fcbb0206ae456dd6553551cd0039c92d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 30 Oct 2012 10:30:41 +0000 Subject: Update browser enhancments docs. Fixes #339. --- docs/topics/browser-enhancements.md | 49 ++++++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 14 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md index d4e128ae..6a11f0fa 100644 --- a/docs/topics/browser-enhancements.md +++ b/docs/topics/browser-enhancements.md @@ -2,42 +2,63 @@ > "There are two noncontroversial uses for overloaded POST. The first is to *simulate* HTTP's uniform interface for clients like web browsers that don't support PUT or DELETE" > -> — [RESTful Web Services](1), Leonard Richardson & Sam Ruby. +> — [RESTful Web Services][cite], Leonard Richardson & Sam Ruby. ## Browser based PUT, DELETE, etc... -**TODO: Preamble.** Note that this is the same strategy as is used in [Ruby on Rails](2). +REST framework supports browser-based `PUT`, `DELETE` and other methods, by +overloading `POST` requests using a hidden form field. + +Note that this is the same strategy as is used in [Ruby on Rails][rails]. For example, given the following form: + + `request.method` would return `"DELETE"`. ## Browser based submission of non-form content -Browser-based submission of content types other than form are supported by using form fields named `_content` and `_content_type`: +Browser-based submission of content types other than form are supported by +using form fields named `_content` and `_content_type`: For example, given the following form: + + + -`request.content_type` would return `"application/json"`, and `request.stream` would return `"{'count': 1}"` +`request.content_type` would return `"application/json"`, and +`request.stream` would return `"{'count': 1}"` ## URL based accept headers +REST framework can take `?accept=application/json` style URL parameters, +which allow the `Accept` header to be overridden. + +This can be useful for testing the API from a web browser, where you don't +have any control over what is sent in the `Accept` header. + ## URL based format suffixes +REST framework can take `?format=json` style URL parameters, which can be a +useful shortcut for determing which content type should be returned from +the view. + +This is a more concise than using the `accept` override, but it also gives +you less control. (For example you can't specify any media type parameters) + ## Doesn't HTML5 support PUT and DELETE forms? -Nope. It was at one point intended to support `PUT` and `DELETE` forms, but was later [dropped from the spec](3). There remains [ongoing discussion](4) about adding support for `PUT` and `DELETE`, as well as how to support content types other than form-encoded data. +Nope. It was at one point intended to support `PUT` and `DELETE` forms, but +was later [dropped from the spec][html5]. There remains +[ongoing discussion][put_delete] about adding support for `PUT` and `DELETE`, +as well as how to support content types other than form-encoded data. -[1]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 -[2]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work -[3]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 -[4]: http://amundsen.com/examples/put-delete-forms/ +[cite]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 +[rails]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work +[html5]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 +[put_delete]: http://amundsen.com/examples/put-delete-forms/ -- cgit v1.2.3 From 41ab18b13ec6d96906463a3b05680226c7245b6d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 30 Oct 2012 12:23:17 +0000 Subject: Docs update --- docs/topics/rest-framework-2-announcement.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md index 7b97af73..e77575b2 100644 --- a/docs/topics/rest-framework-2-announcement.md +++ b/docs/topics/rest-framework-2-announcement.md @@ -6,7 +6,13 @@ What it is, and why you should care > > — [Roy Fielding][cite] -REST framework 2 is an almost complete reworking of the original framework, which comprehensivly addresses some of the original design issues. +--- + +**Announcement:** REST framework 2 released - Tue 30th Oct 2012 + +--- + +REST framework 2 is an almost complete reworking of the original framework, which comprehensively addresses some of the original design issues. Because the latest version should be considered a re-release, rather than an incremental improvement, we've skipped a version, and called this release Django REST framework 2.0. -- cgit v1.2.3 From 4cdd0b845e10c433358f210c84a2b3fe28543c68 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 30 Oct 2012 13:59:31 +0000 Subject: Final docs tweaks for 2.0 --- docs/topics/credits.md | 4 ++++ docs/topics/rest-framework-2-announcement.md | 8 +++++++- 2 files changed, 11 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 3b430e42..69d57802 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -62,6 +62,8 @@ Project hosting is with [GitHub]. Continuous integration testing is managed with [Travis CI][travis-ci]. +The [live sandbox][sandbox] is hosted on [Heroku]. + Various inspiration taken from the [Piston], [Tastypie] and [Dagny] projects. Development of REST framework 2.0 was sponsored by [DabApps]. @@ -83,6 +85,8 @@ To contact the author directly: [tastypie]: https://github.com/toastdriven/django-tastypie [dagny]: https://github.com/zacharyvoase/dagny [dabapps]: http://lab.dabapps.com +[sandbox]: http://restframework.herokuapp.com/ +[heroku]: http://www.heroku.com/ [tomchristie]: https://github.com/tomchristie [markotibold]: https://github.com/markotibold diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md index e77575b2..885d1918 100644 --- a/docs/topics/rest-framework-2-announcement.md +++ b/docs/topics/rest-framework-2-announcement.md @@ -1,6 +1,6 @@ # Django REST framework 2 -What it is, and why you should care +What it is, and why you should care. > Most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. > @@ -86,9 +86,15 @@ We're really pleased with how the docs style looks - it's simple and clean, is e In short, we've engineered the hell outta this thing, and we're incredibly proud of the result. +If you're interested please take a browse around the documentation. [The tutorial][tut] is a great place to get started. + +There's also a [live sandbox version of the tutorial API][sandbox] available for testing. + [cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-724 [quote1]: https://twitter.com/kobutsu/status/261689665952833536 [quote2]: https://groups.google.com/d/msg/django-rest-framework/heRGHzG6BWQ/ooVURgpwVC0J [quote3]: https://groups.google.com/d/msg/django-rest-framework/flsXbvYqRoY/9lSyntOf5cUJ [image]: ../img/quickstart.png [readthedocs]: https://readthedocs.org/ +[tut]: ../tutorial/1-serialization.md +[sandbox]: http://restframework.herokuapp.com/ -- cgit v1.2.3