diff options
Diffstat (limited to 'docs/topics')
| -rw-r--r-- | docs/topics/2.3-announcement.md | 6 | ||||
| -rw-r--r-- | docs/topics/2.4-announcement.md (renamed from docs/topics/2.4-accouncement.md) | 24 | ||||
| -rw-r--r-- | docs/topics/contributing.md | 8 | ||||
| -rw-r--r-- | docs/topics/kickstarter-announcement.md | 7 | ||||
| -rw-r--r-- | docs/topics/release-notes.md | 34 | ||||
| -rw-r--r-- | docs/topics/third-party-resources.md | 92 |
6 files changed, 156 insertions, 15 deletions
diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md index ba435145..7c800afa 100644 --- a/docs/topics/2.3-announcement.md +++ b/docs/topics/2.3-announcement.md @@ -15,7 +15,7 @@ As an example of just how simple REST framework APIs can now be, here's an API w """ A REST framework API for viewing and editing users and groups. """ - from django.conf.urls.defaults import url, patterns, include + from django.conf.urls.defaults import url, include from django.contrib.auth.models import User, Group from rest_framework import viewsets, routers @@ -36,10 +36,10 @@ As an example of just how simple REST framework APIs can now be, here's an API w # Wire up our API using automatic URL routing. # Additionally, we include login URLs for the browseable API. - urlpatterns = patterns('', + urlpatterns = [ url(r'^', include(router.urls)), url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) - ) + ] The best place to get started with ViewSets and Routers is to take a look at the [newest section in the tutorial][part-6], which demonstrates their usage. diff --git a/docs/topics/2.4-accouncement.md b/docs/topics/2.4-announcement.md index d8e264ff..8e4f3bb2 100644 --- a/docs/topics/2.4-accouncement.md +++ b/docs/topics/2.4-announcement.md @@ -15,6 +15,18 @@ The optional authtoken application now includes support for *both* Django 1.7 sc **If you are using authtoken, and you want to continue using `south`, you must upgrade your `south` package to version 1.0.** +## Deprecation of `.model` view attribute + +The `.model` attribute on view classes is an optional shortcut for either or both of `.serializer_class` and `.queryset`. Its usage results in more implicit, less obvious behavior. + +The documentation has previously stated that usage of the more explicit style is prefered, and we're now taking that one step further and deprecating the usage of the `.model` shortcut. + +Doing so will mean that there are cases of API code where you'll now need to include a serializer class where you previously were just using the `.model` shortcut. However we firmly believe that it is the right trade-off to make. + +Removing the shortcut takes away an unneccessary layer of abstraction, and makes your codebase more explicit without any significant extra complexity. It also results in better consistency, as there's now only one way to set the serializer class and queryset attributes for the view, instead of two. + +The `DEFAULT_MODEL_SERIALIZER_CLASS` API setting is now also deprecated. + ## Updated test runner We now have a new test runner for developing against the project,, that uses the excellent [py.test](http://pytest.org) library. @@ -116,7 +128,7 @@ There are also a number of other features and bugfixes as [listed in the release Smarter [client IP identification for throttling][client-ip-identification], with the addition of the `NUM_PROXIES` setting. -Added the standardized `Retry-After` header to throttled responses, as per [RFC 6585](http://tools.ietf.org/html/rfc6585). This should now be used in preference to the custom `X-Trottle-Wait-Seconds` header which will be fully deprecated in 3.0. +Added the standardized `Retry-After` header to throttled responses, as per [RFC 6585](http://tools.ietf.org/html/rfc6585). This should now be used in preference to the custom `X-Throttle-Wait-Seconds` header which will be fully deprecated in 3.0. ## Deprecations @@ -151,10 +163,10 @@ The next planned release will be 3.0, featuring an improved and simplified seria Once again, many thanks to all the generous [backers and sponsors][kickstarter-sponsors] who've helped make this possible! [lts-releases]: https://docs.djangoproject.com/en/dev/internals/release-process/#long-term-support-lts-releases -[2-4-release-notes]: ./topics/release-notes/#240 -[view-name-and-description-settings]: ../api-guide/settings/#view-names-and-descriptions -[client-ip-identification]: ../api-guide/throttling/#how-clients-are-identified -[2-3-announcement]: ./topics/2.3-announcement +[2-4-release-notes]: release-notes#240 +[view-name-and-description-settings]: ../api-guide/settings#view-names-and-descriptions +[client-ip-identification]: ../api-guide/throttling#how-clients-are-identified +[2-3-announcement]: 2.3-announcement [github-labels]: https://github.com/tomchristie/django-rest-framework/issues [github-milestones]: https://github.com/tomchristie/django-rest-framework/milestones -[kickstarter-sponsors]: ./topics/kickstarter-announcement/#sponsors +[kickstarter-sponsors]: kickstarter-announcement#sponsors diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 3400bc8f..4fafb1b1 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -210,7 +210,9 @@ We recommend the [`django-reusable-app`][django-reusable-app] template as a good ## Linking to your package -Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main REST framework documentation. +Once your package is decently documented and available on PyPI open a pull request or issue, and we'll add a link to it from the main REST framework documentation. You can add your package under **Third party packages** of the API Guide section that best applies, like [Authentication][authentication] or [Permissions][permissions]. You can also link your package under the [Third Party Resources][third-party-resources] section. + +We also suggest adding it to the [REST Framework][rest-framework-grid] grid on Django Packages. [cite]: http://www.w3.org/People/Berners-Lee/FAQ.html [code-of-conduct]: https://www.djangoproject.com/conduct/ @@ -225,3 +227,7 @@ Once your package is decently documented and available on PyPI open a pull reque [docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs [mou]: http://mouapp.com/ [django-reusable-app]: https://github.com/dabapps/django-reusable-app +[authentication]: ../api-guide/authentication.md +[permissions]: ../api-guide/permissions.md +[third-party-resources]: third-party-resources.md +[rest-framework-grid]: https://www.djangopackages.com/grids/g/django-rest-framework/ diff --git a/docs/topics/kickstarter-announcement.md b/docs/topics/kickstarter-announcement.md index 6d091064..7d1f6d0e 100644 --- a/docs/topics/kickstarter-announcement.md +++ b/docs/topics/kickstarter-announcement.md @@ -82,7 +82,7 @@ Our gold sponsors include companies large and small. Many thanks for their signi <li><a href="https://opbeat.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-opbeat.png);">Opbeat</a></li> <li><a href="https://koordinates.com" rel="nofollow" style="background-image:url(../img/sponsors/2-koordinates.png);">Koordinates</a></li> <li><a href="http://pulsecode.ca" rel="nofollow" style="background-image:url(../img/sponsors/2-pulsecode.png);">Pulsecode Inc.</a></li> -<li><a href="http://singinghorsestudio.com" rel="nofollow" style="background-image:url(../img/sponsors/2-singing-horse.png);">Singing Horse Studio. Ltd.</a></li> +<li><a href="http://singinghorsestudio.com" rel="nofollow" style="background-image:url(../img/sponsors/2-singing-horse.png);">Singing Horse Studio Ltd.</a></li> <li><a href="https://www.heroku.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-heroku.png);">Heroku</a></li> <li><a href="https://www.galileo-press.de/" rel="nofollow" style="background-image:url(../img/sponsors/2-galileo_press.png);">Galileo Press</a></li> <li><a href="http://www.securitycompass.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-security_compass.png);">Security Compass</a></li> @@ -92,13 +92,12 @@ Our gold sponsors include companies large and small. Many thanks for their signi <li><a href="http://crypticocorp.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-cryptico.png);">Cryptico Corp</a></li> <li><a href="http://www.nexthub.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-nexthub.png);">NextHub</a></li> <li><a href="https://www.compile.com/" rel="nofollow" style="background-image:url(../img/sponsors/2-compile.png);">Compile</a></li> +<li><a href="http://wusawork.org" rel="nofollow" style="background-image:url(../img/sponsors/2-wusawork.png);">WusaWork</a></li> <li><a href="http://envisionlinux.org/blog" rel="nofollow">Envision Linux</a></li> </ul> <div style="clear: both; padding-bottom: 40px;"></div> -**Individual backers**: Simon Haugk. - --- ### Silver sponsors @@ -145,7 +144,7 @@ The serious financial contribution that our silver sponsors have made is very mu <div style="clear: both; padding-bottom: 40px;"></div> -**Individual backers**: Paul Hallet, <a href="http://www.paulwhippconsulting.com/">Paul Whipp</a>, Dylan Roy, Jannis Leidel, <a href="https://linovia.com/en/">Xavier Ordoquy</a>, <a href="http://spielmannsolutions.com/">Johannes Spielmann</a>, <a href="http://brooklynhacker.com/">Rob Spectre</a>, <a href="http://chrisheisel.com/">Chris Heisel</a>, Marwan Alsabbagh, Haris Ali, Tuomas Toivonen. +**Individual backers**: Paul Hallett, <a href="http://www.paulwhippconsulting.com/">Paul Whipp</a>, Dylan Roy, Jannis Leidel, <a href="https://linovia.com/en/">Xavier Ordoquy</a>, <a href="http://spielmannsolutions.com/">Johannes Spielmann</a>, <a href="http://brooklynhacker.com/">Rob Spectre</a>, <a href="http://chrisheisel.com/">Chris Heisel</a>, Marwan Alsabbagh, Haris Ali, Tuomas Toivonen. --- diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index a2b4782f..16589f3b 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -10,7 +10,7 @@ Minor version numbers (0.0.x) are used for changes that are API compatible. You Medium version numbers (0.x.0) may include API changes, in line with the [deprecation policy][deprecation-policy]. You should read the release notes carefully before upgrading between medium point releases. -Major version numbers (x.0.0) are reserved for substantial project milestones. No major point releases are currently planned. +Major version numbers (x.0.0) are reserved for substantial project milestones. ## Deprecation policy @@ -40,14 +40,45 @@ You can determine your currently installed version using `pip freeze`: ## 2.4.x series +### 2.4.3 + +**Date**: [19th September 2014](https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.3+Release%22+). + +* Support translatable view docstrings being displayed in the browsable API. +* Support [encoded `filename*`][rfc-6266] in raw file uploads with `FileUploadParser`. +* Allow routers to support viewsets that don't include any list routes or that don't include any detail routes. +* Don't render an empty login control in browsable API if `login` view is not included. +* CSRF exemption performed in `.as_view()` to prevent accidental omission if overriding `.dispatch()`. +* Login on browsable API now displays validation errors. +* Bugfix: Fix migration in `authtoken` application. +* Bugfix: Allow selection of integer keys in nested choices. +* Bugfix: Return `None` instead of `'None'` in `CharField` with `allow_none=True`. +* Bugfix: Ensure custom model fields map to equivelent serializer fields more reliably. +* Bugfix: `DjangoFilterBackend` no longer quietly changes queryset ordering. + +### 2.4.2 + +**Date**: [3rd September 2014](https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.2+Release%22+). + +* Bugfix: Fix broken pagination for 2.4.x series. + +### 2.4.1 + +**Date**: [1st September 2014](https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.1+Release%22+). + +* Bugfix: Fix broken login template for browsable API. + ### 2.4.0 +**Date**: [29th August 2014](https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%222.4.0+Release%22+). + **Django version requirements**: The lowest supported version of Django is now 1.4.2. **South version requirements**: This note applies to any users using the optional `authtoken` application, which includes an associated database migration. You must now *either* upgrade your `south` package to version 1.0, *or* instead use the built-in migration support available with Django 1.7. * Added compatibility with Django 1.7's database migration support. * New test runner, using `py.test`. +* Deprecated `.model` view attribute in favor of explicit `.queryset` and `.serializer_class` attributes. The `DEFAULT_MODEL_SERIALIZER_CLASS` setting is also deprecated. * `@detail_route` and `@list_route` decorators replace `@action` and `@link`. * Support customizable view name and description functions, using the `VIEW_NAME_FUNCTION` and `VIEW_DESCRIPTION_FUNCTION` settings. * Added `NUM_PROXIES` setting for smarter client IP identification. @@ -702,3 +733,4 @@ This change will not affect user code, so long as it's following the recommended [2.1.0-notes]: https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion [announcement]: rest-framework-2-announcement.md [#582]: https://github.com/tomchristie/django-rest-framework/issues/582 +[rfc-6266]: http://tools.ietf.org/html/rfc6266#section-4.3 diff --git a/docs/topics/third-party-resources.md b/docs/topics/third-party-resources.md new file mode 100644 index 00000000..0317dd64 --- /dev/null +++ b/docs/topics/third-party-resources.md @@ -0,0 +1,92 @@ +# Third Party Resources + +Django REST Framework has a growing community of developers, packages, and resources. + +Check out a grid detailing all the packages and ecosystem around Django REST Framework at [Django Packages](https://www.djangopackages.com/grids/g/django-rest-framework/). + +To submit new content, [open an issue](https://github.com/tomchristie/django-rest-framework/issues/new) or [create a pull request](https://github.com/tomchristie/django-rest-framework/). + +## Libraries and Extensions + +### Authentication + +* [djangorestframework-digestauth](https://github.com/juanriaza/django-rest-framework-digestauth) - Provides Digest Access Authentication support. +* [django-oauth-toolkit](https://github.com/evonove/django-oauth-toolkit) - Provides OAuth 2.0 support. +* [doac](https://github.com/Rediker-Software/doac) - Provides OAuth 2.0 support. +* [djangorestframework-jwt](https://github.com/GetBlimp/django-rest-framework-jwt) - Provides JSON Web Token Authentication support. +* [hawkrest](https://github.com/kumar303/hawkrest) - Provides Hawk HTTP Authorization. +* [djangorestframework-httpsignature](https://github.com/etoccalino/django-rest-framework-httpsignature) - Provides an easy to use HTTP Signature Authentication mechanism. +* [djoser](https://github.com/sunscrapers/djoser) - Provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation. + +### Permissions + +* [drf-any-permissions](https://github.com/kevin-brown/drf-any-permissions) - Provides alternative permission handling. +* [djangorestframework-composed-permissions](https://github.com/niwibe/djangorestframework-composed-permissions) - Provides a simple way to define complex permissions. +* [rest_condition](https://github.com/caxap/rest_condition) - Another extension for building complex permissions in a simple and convenient way. + +### Serializers + +* [django-rest-framework-mongoengine](https://github.com/umutbozkurt/django-rest-framework-mongoengine) - Serializer class that supports using MongoDB as the storage layer for Django REST framework. +* [djangorestframework-gis](https://github.com/djangonauts/django-rest-framework-gis) - Geographic add-ons +* [djangorestframework-hstore](https://github.com/djangonauts/django-rest-framework-hstore) - Serializer class to support django-hstore DictionaryField model field and its schema-mode feature. + +### Serializer fields + +* [drf-compound-fields](https://github.com/estebistec/drf-compound-fields) - Provides "compound" serializer fields, such as lists of simple values. +* [django-extra-fields](https://github.com/Hipo/drf-extra-fields) - Provides extra serializer fields. + +### Views + +* [djangorestframework-bulk](https://github.com/miki725/django-rest-framework-bulk) - Implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests. + +### Routers + +* [drf-nested-routers](https://github.com/alanjds/drf-nested-routers) - Provides routers and relationship fields for working with nested resources. +* [wq.db.rest](http://wq.io/docs/about-rest) - Provides an admin-style model registration API with reasonable default URLs and viewsets. + +### Parsers + +* [djangorestframework-msgpack](https://github.com/juanriaza/django-rest-framework-msgpack) - Provides MessagePack renderer and parser support. +* [djangorestframework-camel-case](https://github.com/vbabiy/djangorestframework-camel-case) - Provides camel case JSON renderers and parsers. + +### Renderers + +* [djangorestframework-csv](https://github.com/mjumbewu/django-rest-framework-csv) - Provides CSV renderer support. +* [drf_ujson](https://github.com/gizmag/drf-ujson-renderer) - Implements JSON rendering using the UJSON package. +* [Django REST Pandas](https://github.com/wq/django-rest-pandas) - Pandas DataFrame-powered renderers including Excel, CSV, and SVG formats. + +### Filtering + +* [djangorestframework-chain](https://github.com/philipn/django-rest-framework-chain) - Allows arbitrary chaining of both relations and lookup filters. + +### Misc + +* [djangorestrelationalhyperlink](https://github.com/fredkingham/django_rest_model_hyperlink_serializers_project) - A hyperlinked serialiser that can can be used to alter relationships via hyperlinks, but otherwise like a hyperlink model serializer. +* [django-rest-swagger](https://github.com/marcgibbons/django-rest-swagger) - An API documentation generator for Swagger UI. +* [django-rest-framework-proxy ](https://github.com/eofs/django-rest-framework-proxy) - Proxy to redirect incoming request to another API server. +* [gaiarestframework](https://github.com/AppsFuel/gaiarestframework) - Utils for django-rest-framewok +* [drf-extensions](https://github.com/chibisov/drf-extensions) - A collection of custom extensions +* [ember-data-django-rest-adapter](https://github.com/toranb/ember-data-django-rest-adapter) - An ember-data adapter + +## Tutorials + +* [Beginner's Guide to the Django Rest Framework](http://code.tutsplus.com/tutorials/beginners-guide-to-the-django-rest-framework--cms-19786) +* [Getting Started with Django Rest Framework and AngularJS](http://blog.kevinastone.com/getting-started-with-django-rest-framework-and-angularjs.html) +* [End to end web app with Django-Rest-Framework & AngularJS](http://blog.mourafiq.com/post/55034504632/end-to-end-web-app-with-django-rest-framework) +* [Start Your API - django-rest-framework part 1](https://godjango.com/41-start-your-api-django-rest-framework-part-1/) +* [Permissions & Authentication - django-rest-framework part 2](https://godjango.com/43-permissions-authentication-django-rest-framework-part-2/) +* [ViewSets and Routers - django-rest-framework part 3](https://godjango.com/45-viewsets-and-routers-django-rest-framework-part-3/) +* [Django Rest Framework User Endpoint](http://richardtier.com/2014/02/25/django-rest-framework-user-endpoint/) +* [Check credentials using Django Rest Framework](http://richardtier.com/2014/03/06/110/) + +## Videos + +* [Ember and Django Part 1 (Video)](http://www.neckbeardrepublic.com/screencasts/ember-and-django-part-1) +* [Django Rest Framework Part 1 (Video)](http://www.neckbeardrepublic.com/screencasts/django-rest-framework-part-1) +* [Pyowa July 2013 - Django Rest Framework (Video)](http://www.youtube.com/watch?v=E1ZrehVxpBo) +* [django-rest-framework and angularjs (Video)](http://www.youtube.com/watch?v=Q8FRBGTJ020) + +## Articles + +* [Web API performance: profiling Django REST framework](http://dabapps.com/blog/api-performance-profiling-django-rest-framework/) +* [API Development with Django and Django REST Framework](https://bnotions.com/api-development-with-django-and-django-rest-framework/) |