Merge branch 'restframework2' of git://github.com/tomchristie/django-rest-framework into improved-view-decorators

* 'restframework2' of git://github.com/tomchristie/django-rest-framework: (56 commits) Bits of cleanup Add request.QUERY_PARAMS Add readonly 'id' field Tweak browseable API Don't display readonly fields Fix some bits of serialization Add csrf note Fix incorrect bit of tutorial Added tox.ini Tweak media_type -> accepted_media_type. Need to document, but marginally less confusing Tweak media_type -> accepted_media_type. Need to document, but marginally less confusing Tweak media_type -> accepted_media_type. Need to document, but marginally less confusing Clean up bits of templates etc Hack out bunch of unneccesary private methods on View class Clean up template tags Remove dumbass __all__ variables Remove old 'djangorestframework directories Change package name: djangorestframework -> rest_framework Dont strip final '/' Use get_script_prefix to play nicely if not installed at the root. ... Conflicts: rest_framework/decorators.py
author: Jamie Matthews 2012-09-26 13:05:21 +0100
committer: Jamie Matthews 2012-09-26 13:05:21 +0100
commit: 01770c53cd9045e6ea054f32b1e40b5d2ff7fe44 (patch)
tree: 657cb66f92d78add3b2f587754387832043168e6 /docs/topics
parent: f6488cb0589d3b11fb8d831e00d1389f3fff74b6 (diff)
parent: 09a445b257532be69ffab69a3f62b84bfa90463d (diff)
download: django-rest-framework-01770c53cd9045e6ea054f32b1e40b5d2ff7fe44.tar.bz2
4 files changed, 258 insertions, 0 deletions
diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md
new file mode 100644
index 00000000..ed27752f
--- /dev/null
+++ b/docs/topics/browsable-api.md
@@ -0,0 +1,97 @@
+# 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 `rest_framework` 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][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/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.
+
+### 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 %}
+        <link rel="stylesheet" href="/path/to/my/bootstrap.css" type="text/css">
+    {% endblock %}
+
+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.
+
+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`                  - `<meta>` tag that blocks crawlers
+* `bodyclass`                  - (empty) class attribute for the `<body>`
+* `bootstrap_theme`            - CSS for the Bootstrap theme
+* `bootstrap_navbar_variant`   - CSS class for the 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 `<head>`
+* `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][bcomponents] 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`        : The view can accept a format override
+* `METHOD_PARAM`        : The view can accept a method override
+
+#### 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.
+
+
+[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
+
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.
+
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
diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md
new file mode 100644
index 00000000..46a4c9d7
--- /dev/null
+++ b/docs/topics/rest-hypermedia-hateoas.md
@@ -0,0 +1,52 @@
+# REST, Hypermedia & HATEOAS
+
+> You keep using that word "REST". I do not think it means what you think it means.
+>
+> &mdash; 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".
+
+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
author	Jamie Matthews	2012-09-26 13:05:21 +0100
committer	Jamie Matthews	2012-09-26 13:05:21 +0100
commit	01770c53cd9045e6ea054f32b1e40b5d2ff7fe44 (patch)
tree	657cb66f92d78add3b2f587754387832043168e6 /docs/topics
parent	f6488cb0589d3b11fb8d831e00d1389f3fff74b6 (diff)
parent	09a445b257532be69ffab69a3f62b84bfa90463d (diff)
download	django-rest-framework-01770c53cd9045e6ea054f32b1e40b5d2ff7fe44.tar.bz2