diff options
Diffstat (limited to 'docs/topics')
| -rw-r--r-- | docs/topics/browser-enhancements.md | 49 | ||||
| -rw-r--r-- | docs/topics/credits.md | 100 | ||||
| -rw-r--r-- | docs/topics/release-notes.md | 251 | ||||
| -rw-r--r-- | docs/topics/rest-framework-2-announcement.md | 100 | ||||
| -rw-r--r-- | docs/topics/rest-hypermedia-hateoas.md | 3 |
5 files changed, 461 insertions, 42 deletions
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: <form action="/news-items/5" method="POST"> - <input type="hidden" name="_method" value="DELETE"> - </form> + <input type="hidden" name="_method" value="DELETE"> + </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: <form action="/news-items/5" method="PUT"> - <input type="hidden" name="_content_type" value="application/json"> - <input name="_content" value="{'count': 1}"> - </form> + <input type="hidden" name="_content_type" value="application/json"> + <input name="_content" value="{'count': 1}"> + </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/ diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 27a56326..b0b00c12 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -2,7 +2,7 @@ The following people have helped make REST framework great. -* Tom Christie - [tomchristie] +* Tom Christie - [tomchristie] * Marko Tibold - [markotibold] * Paul Bagwell - [pbgwl] * Sébastien Piquemal - [sebpiq] @@ -49,6 +49,48 @@ The following people have helped make REST framework great. * Tomi Pajunen - [eofs] * Rob Dobson - [rdobson] * Daniel Vaca Araujo - [diviei] +* Madis Väin - [madisvain] +* Stephan Groß - [minddust] +* Pavel Savchenko - [asfaltboy] +* Otto Yiu - [ottoyiu] +* Jacob Magnusson - [jmagnusson] +* Osiloke Harold Emoekpere - [osiloke] +* Michael Shepanski - [mjs7231] +* Toni Michel - [tonimichel] +* Ben Konrath - [benkonrath] +* Marc Aymerich - [glic3rinu] +* Ludwig Kraatz - [ludwigkraatz] +* Rob Romano - [robromano] +* Eugene Mechanism - [mechanism] +* Jonas Liljestrand - [jonlil] +* Justin Davis - [irrelative] +* Dustin Bachrach - [dbachrach] +* Mark Shirley - [maspwr] +* Olivier Aubert - [oaubert] +* Yuri Prezument - [yprez] +* Fabian Buechler - [fabianbuechler] +* Mark Hughes - [mhsparks] +* Michael van de Waeter - [mvdwaeter] +* Reinout van Rees - [reinout] +* Michael Richards - [justanotherbody] +* Ben Roberts - [roberts81] +* Venkata Subramanian Mahalingam - [annacoder] +* George Kappel - [gkappel] +* Colin Murtaugh - [cmurtaugh] +* Simon Pantzare - [pilt] +* Szymon Teżewski - [sunscrapers] +* Joel Marcotte - [joual] +* Trey Hunner - [treyhunner] +* Roman Akinfold - [akinfold] +* Toran Billups - [toranb] +* Sébastien Béal - [sebastibe] +* Andrew Hankinson - [ahankinson] +* Juan Riaza - [juanriaza] +* Michael Mior - [michaelmior] +* Marc Tamlyn - [mjtamlyn] +* Richard Wackerbarth - [wackerbarth] +* Johannes Spielmann - [shezi] +* James Cleveland - [radiosilence] Many thanks to everyone who's contributed to the project. @@ -60,27 +102,31 @@ 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]. ## Contact -To contact the author directly: +For usage questions please see the [REST framework discussion group][group]. + +You can also contact [@_tomchristie][twitter] directly on twitter. -* twitter: [@_tomchristie][twitter] -* 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 +[github]: https://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 +[sandbox]: http://restframework.herokuapp.com/ +[heroku]: http://www.heroku.com/ +[group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework [tomchristie]: https://github.com/tomchristie [markotibold]: https://github.com/markotibold @@ -129,3 +175,45 @@ 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 +[minddust]: https://github.com/minddust +[asfaltboy]: https://github.com/asfaltboy +[ottoyiu]: https://github.com/OttoYiu +[jmagnusson]: https://github.com/jmagnusson +[osiloke]: https://github.com/osiloke +[mjs7231]: https://github.com/mjs7231 +[tonimichel]: https://github.com/tonimichel +[benkonrath]: https://github.com/benkonrath +[glic3rinu]: https://github.com/glic3rinu +[ludwigkraatz]: https://github.com/ludwigkraatz +[robromano]: https://github.com/robromano +[mechanism]: https://github.com/mechanism +[jonlil]: https://github.com/jonlil +[irrelative]: https://github.com/irrelative +[dbachrach]: https://github.com/dbachrach +[maspwr]: https://github.com/maspwr +[oaubert]: https://github.com/oaubert +[yprez]: https://github.com/yprez +[fabianbuechler]: https://github.com/fabianbuechler +[mhsparks]: https://github.com/mhsparks +[mvdwaeter]: https://github.com/mvdwaeter +[reinout]: https://github.com/reinout +[justanotherbody]: https://github.com/justanotherbody +[roberts81]: https://github.com/roberts81 +[annacoder]: https://github.com/annacoder +[gkappel]: https://github.com/gkappel +[cmurtaugh]: https://github.com/cmurtaugh +[pilt]: https://github.com/pilt +[sunscrapers]: https://github.com/sunscrapers +[joual]: https://github.com/joual +[treyhunner]: https://github.com/treyhunner +[akinfold]: https://github.com/akinfold +[toranb]: https://github.com/toranb +[sebastibe]: https://github.com/sebastibe +[ahankinson]: https://github.com/ahankinson +[juanriaza]: https://github.com/juanriaza +[michaelmior]: https://github.com/michaelmior +[mjtamlyn]: https://github.com/mjtamlyn +[wackerbarth]: https://github.com/wackerbarth +[shezi]: https://github.com/shezi +[radiosilence]: https://github.com/radiosilence diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index a466f4b1..f43dc1d3 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -4,41 +4,239 @@ > > — Eric S. Raymond, [The Cathedral and the Bazaar][cite]. -## 2.0.0 +## Versioning + +Minor version numbers (0.0.x) are used for changes that are API compatible. You should be able to upgrade between minor point releases without any other code changes. + +Medium version numbers (0.x.0) may include minor API changes. You should read the release notes carefully before upgrading between medium point releases. + +Major version numbers (x.0.0) are reserved for project milestones. No major point releases are currently planned. + +--- + +## 2.1.x series + +### Master + +* Support json encoding of timedelta objects. + +### 2.1.16 + +**Date**: 14th Jan 2013 + +* Deprecate django.utils.simplejson in favor of Python 2.6's built-in json module. +* Bugfix: `auto_now`, `auto_now_add` and other `editable=False` fields now default to read-only. +* Bugfix: PK fields now only default to read-only if they are an AutoField or if `editable=False`. +* Bugfix: Validation errors instead of exceptions when serializers receive incorrect types. +* Bugfix: Validation errors instead of exceptions when related fields receive incorrect types. +* Bugfix: Handle ObjectDoesNotExist exception when serializing null reverse one-to-one + +### 2.1.15 + +**Date**: 3rd Jan 2013 + +* Added `PATCH` support. +* Added `RetrieveUpdateAPIView`. +* Remove unused internal `save_m2m` flag on `ModelSerializer.save()`. +* Tweak behavior of hyperlinked fields with an explicit format suffix. +* Relation changes are now persisted in `.save()` instead of in `.restore_object()`. +* Bugfix: Fix issue with FileField raising exception instead of validation error when files=None. +* Bugfix: Partial updates should not set default values if field is not included. + +### 2.1.14 + +**Date**: 31st Dec 2012 + +* Bugfix: ModelSerializers now include reverse FK fields on creation. +* Bugfix: Model fields with `blank=True` are now `required=False` by default. +* Bugfix: Nested serializers now support nullable relationships. + +**Note**: From 2.1.14 onwards, relational fields move out of the `fields.py` module and into the new `relations.py` module, in order to separate them from regular data type fields, such as `CharField` and `IntegerField`. + +This change will not affect user code, so long as it's following the recommended import style of `from rest_framework import serializers` and referring to fields using the style `serializers.PrimaryKeyRelatedField`. + + +### 2.1.13 + +**Date**: 28th Dec 2012 + +* Support configurable `STATICFILES_STORAGE` storage. +* Bugfix: Related fields now respect the required flag, and may be required=False. + +### 2.1.12 + +**Date**: 21st Dec 2012 + +* Bugfix: Fix bug that could occur using ChoiceField. +* Bugfix: Fix exception in browseable API on DELETE. +* Bugfix: Fix issue where pk was was being set to a string if set by URL kwarg. + +### 2.1.11 + +**Date**: 17th Dec 2012 + +* Bugfix: Fix issue with M2M fields in browseable API. + +### 2.1.10 + +**Date**: 17th Dec 2012 + +* Bugfix: Ensure read-only fields don't have model validation applied. +* Bugfix: Fix hyperlinked fields in paginated results. + +### 2.1.9 + +**Date**: 11th Dec 2012 + +* Bugfix: Fix broken nested serialization. +* Bugfix: Fix `Meta.fields` only working as tuple not as list. +* Bugfix: Edge case if unnecessarily specifying `required=False` on read only field. + +### 2.1.8 + +**Date**: 8th Dec 2012 + +* Fix for creating nullable Foreign Keys with `''` as well as `None`. +* Added `null=<bool>` related field option. + +### 2.1.7 + +**Date**: 7th Dec 2012 + +* Serializers now properly support nullable Foreign Keys. +* Serializer validation now includes model field validation, such as uniqueness constraints. +* Support 'true' and 'false' string values for BooleanField. +* Added pickle support for serialized data. +* Support `source='dotted.notation'` style for nested serializers. +* Make `Request.user` settable. +* Bugfix: Fix `RegexField` to work with `BrowsableAPIRenderer`. + +### 2.1.6 + +**Date**: 23rd Nov 2012 + +* Bugfix: Unfix DjangoModelPermissions. (I am a doofus.) + +### 2.1.5 + +**Date**: 23rd Nov 2012 + +* Bugfix: Fix DjangoModelPermissions. + +### 2.1.4 + +**Date**: 22nd Nov 2012 + +* Support for partial updates with serializers. +* Added `RegexField`. +* Added `SerializerMethodField`. +* Serializer performance improvements. +* Added `obtain_token_view` to get tokens when using `TokenAuthentication`. +* Bugfix: Django 1.5 configurable user support for `TokenAuthentication`. + +### 2.1.3 + +**Date**: 16th Nov 2012 + +* Added `FileField` and `ImageField`. For use with `MultiPartParser`. +* Added `URLField` and `SlugField`. +* Support for `read_only_fields` on `ModelSerializer` classes. +* Support for clients overriding the pagination page sizes. Use the `PAGINATE_BY_PARAM` setting or set the `paginate_by_param` attribute on a generic view. +* 201 Responses now return a 'Location' header. +* Bugfix: Serializer fields now respect `max_length`. + +### 2.1.2 + +**Date**: 9th Nov 2012 + +* **Filtering support.** +* Bugfix: Support creation of objects with reverse M2M relations. + +### 2.1.1 + +**Date**: 7th Nov 2012 + +* Support use of HTML exception templates. Eg. `403.html` +* Hyperlinked fields take optional `slug_field`, `slug_url_kwarg` and `pk_url_kwarg` arguments. +* Bugfix: Deal with optional trailing slashes properly when generating breadcrumbs. +* Bugfix: Make textareas same width as other fields in browsable API. +* Private API change: `.get_serializer` now uses same `instance` and `data` ordering as serializer initialization. + +### 2.1.0 + +**Date**: 5th Nov 2012 + +* **Serializer `instance` and `data` keyword args have their position swapped.** +* `queryset` argument is now optional on writable model fields. +* Hyperlinked related fields optionally take `slug_field` and `slug_url_kwarg` arguments. +* Support Django's cache framework. +* Minor field improvements. (Don't stringify dicts, more robust many-pk fields.) +* Bugfix: Support choice field in Browseable API. +* Bugfix: Related fields with `read_only=True` do not require a `queryset` argument. + +**API-incompatible changes**: Please read [this thread][2.1.0-notes] regarding the `instance` and `data` keyword args before updating to 2.1.0. + +--- + +## 2.0.x series + +### 2.0.2 + +**Date**: 2nd Nov 2012 + +* Fix issues with pk related fields in the browsable API. + +### 2.0.1 + +**Date**: 1st Nov 2012 + +* Add support for relational fields in the browsable API. +* Added SlugRelatedField and ManySlugRelatedField. +* If PUT creates an instance return '201 Created', instead of '200 OK'. + +### 2.0.0 + +**Date**: 30th Oct 2012 * **Fix all of the things.** (Well, almost.) -* For more information please see the [2.0 migration guide][migration]. +* For more information please see the [2.0 announcement][announcement]. --- -## 0.4.0 +## 0.4.x series + +### 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 +* Fix internet explorer ajax behavior * Minor xml and yaml fixes -* Improve setup (eg use staticfiles, not the defunct ADMIN_MEDIA_PREFIX) +* Improve setup (e.g. use staticfiles, not the defunct ADMIN_MEDIA_PREFIX) * Sensible absolute URL generation, not using hacky set_script_prefix -## 0.3.3 +--- + +## 0.3.x series + +### 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) + - Easier to override. Won't conflict with customized admin styles (e.g. 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 + - Too magical. Explicit is better than implicit. +* Saner template variable auto-escaping. +* Tidier setup.py * Updated for URLObject 2.0 * Bugfixes: - Bug with PerUserThrottling when user contains unicode chars. -## 0.3.2 +### 0.3.2 * Bugfixes: * Fix 403 for POST and PUT from the UI with UserLoggedInAuthentication (#115) @@ -50,37 +248,41 @@ * 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 +### 0.3.1 * [not documented] -## 0.3.0 +### 0.3.0 * JSONP Support * Bugfixes, including support for latest markdown release -## 0.2.4 +--- + +## 0.2.x series + +### 0.2.4 * Fix broken IsAdminUser permission. * OPTIONS support. * XMLParser. * Drop mentions of Blog, BitBucket. -## 0.2.3 +### 0.2.3 * Fix some throttling bugs. * ``X-Throttle`` header on throttling. * Support for nesting resources on related models. -## 0.2.2 +### 0.2.2 * Throttling support complete. -## 0.2.1 +### 0.2.1 * Couple of simple bugfixes over 0.2.0 -## 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. @@ -104,13 +306,20 @@ * 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 +--- + +## 0.1.x series + +### 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 +### 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 +[staticfiles14]: https://docs.djangoproject.com/en/1.4/howto/static-files/#with-a-template-tag +[staticfiles13]: https://docs.djangoproject.com/en/1.3/howto/static-files/#with-a-template-tag +[2.1.0-notes]: https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion +[announcement]: rest-framework-2-announcement.md diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md new file mode 100644 index 00000000..885d1918 --- /dev/null +++ b/docs/topics/rest-framework-2-announcement.md @@ -0,0 +1,100 @@ +# 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] + +--- + +**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. + +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. + +## 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. + +![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. + +## Summary + +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/ diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index d7646892..10ab9dfe 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] 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. +What REST framework doesn't do is give you is machine readable hypermedia formats such as [HAL][hal], [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 @@ -44,6 +44,7 @@ What REST framework doesn't do is give you is machine readable hypermedia format [readinglist]: http://blog.steveklabnik.com/posts/2012-02-27-hypermedia-api-reading-list [maturitymodel]: http://martinfowler.com/articles/richardsonMaturityModel.html +[hal]: http://stateless.co/hal_specification.html [collection]: http://www.amundsen.com/media-types/collection/ [microformats]: http://microformats.org/wiki/Main_Page [serialization]: ../api-guide/serializers.md |