From 997a93ac2e2f1e7ac9d7f9d6a7e477752763c38a Mon Sep 17 00:00:00 2001 From: Sebastien Beal Date: Sun, 7 Jul 2013 19:04:47 +0900 Subject: Add info about autocomplete widgets for browsable API --- docs/topics/browsable-api.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index 85f1faff..8150629c 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -24,8 +24,8 @@ To customize the default style, create a template called `rest_framework/api.htm **templates/rest_framework/api.html** {% extends "rest_framework/base.html" %} - - ... # Override blocks with required customizations + + ... # Override blocks with required customizations ### Overriding the default theme @@ -96,7 +96,7 @@ You can add your site name or branding by including the branding block: {% block branding %}

My Site Name

{% endblock %} - + You can also customize the style by adding the `bootstrap_theme` or `style` block similar to `api.html`. ### Advanced Customization @@ -125,6 +125,28 @@ 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. +#### Autocompletion + +When a `ChoiceField` has too many items, the browsable API rendering can become very slow because of all of the options loading. One solution is to replace the selector by an autocomplete widget for example using [django-autocomplete-light]. In addition to the default steps to set up your Autocomplete class, add the the following to the `api.html` template: + + {% block script %} + {{ block.super }} + {% include 'autocomplete_light/static.html' %} + {% endblock %} + +And add the `autocomplete_light.ChoiceWidget` for your Autocomplete class to the serializer field. + + import autocomplete_light + + class BookSerializer(serializers.ModelSerializer): + author = serializers.ChoiceField( + widget=autocomplete_light.ChoiceWidget('AuthorAutocomplete') + ) + + class Meta: + model = Book + + [cite]: http://en.wikiquote.org/wiki/Alfred_North_Whitehead [drfreverse]: ../api-guide/reverse.md [ffjsonview]: https://addons.mozilla.org/en-US/firefox/addon/jsonview/ @@ -136,4 +158,4 @@ For more advanced customization, such as not having a Bootstrap basis or tighter [bswatch]: http://bootswatch.com/ [bcomponents]: http://twitter.github.com/bootstrap/components.html [bcomponentsnav]: http://twitter.github.com/bootstrap/components.html#navbar - +[django-autocomplete-light]: https://github.com/yourlabs/django-autocomplete-light -- cgit v1.2.3 From f94ce6e7cbb0fe95725d41ece8cfb249248ac6ea Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Jul 2013 13:13:56 +0100 Subject: Added @gertjanol for work on #976 - thank you :) --- 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 e6fb9134..42b28d26 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -145,6 +145,7 @@ The following people have helped make REST framework great. * Philip Douglas - [freakydug] * Igor Kalat - [trwired] * Rudolf Olah - [omouse] +* Gertjan Oude Lohuis - [gertjanol] Many thanks to everyone who's contributed to the project. @@ -326,3 +327,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [freakydug]: https://github.com/freakydug [trwired]: https://github.com/trwired [omouse]: https://github.com/omouse +[gertjanol]: https://github.com/gertjanol -- cgit v1.2.3 From 77364d2b84aa20030f579076a4b2a92a2c9d5dd4 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Jul 2013 14:00:53 +0100 Subject: Add screenshot, and tweak docs --- docs/topics/browsable-api.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index 8150629c..895b3c5f 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -127,14 +127,16 @@ For more advanced customization, such as not having a Bootstrap basis or tighter #### Autocompletion -When a `ChoiceField` has too many items, the browsable API rendering can become very slow because of all of the options loading. One solution is to replace the selector by an autocomplete widget for example using [django-autocomplete-light]. In addition to the default steps to set up your Autocomplete class, add the the following to the `api.html` template: +When a `ChoiceField` has too many items, rendering the widget containing all the options can become very slow, and cause the browsable API rendering to perform poorly. One solution is to replace the selector by an autocomplete widget, that only loads and renders a subset of the available options as needed. + +There are [a variety of packages for autocomplete widgets][autocomplete-packages], such as [django-autocomplete-light][django-autocomplete-light]. To setup `django-autocomplete-light`, follow the [installation documentation][django-autocomplete-light-install], add the the following to the `api.html` template: {% block script %} {{ block.super }} {% include 'autocomplete_light/static.html' %} {% endblock %} -And add the `autocomplete_light.ChoiceWidget` for your Autocomplete class to the serializer field. +You can now add the `autocomplete_light.ChoiceWidget` widget to the serializer field. import autocomplete_light @@ -146,6 +148,13 @@ And add the `autocomplete_light.ChoiceWidget` for your Autocomplete class to the class Meta: model = Book +--- + +![Autocomplete][autocomplete-image] + +*Screenshot of the autocomplete-light widget* + +--- [cite]: http://en.wikiquote.org/wiki/Alfred_North_Whitehead [drfreverse]: ../api-guide/reverse.md @@ -158,4 +167,7 @@ And add the `autocomplete_light.ChoiceWidget` for your Autocomplete class to the [bswatch]: http://bootswatch.com/ [bcomponents]: http://twitter.github.com/bootstrap/components.html [bcomponentsnav]: http://twitter.github.com/bootstrap/components.html#navbar +[autocomplete-packages]: https://www.djangopackages.com/grids/g/auto-complete/ [django-autocomplete-light]: https://github.com/yourlabs/django-autocomplete-light +[django-autocomplete-light-install]: http://django-autocomplete-light.readthedocs.org/en/latest/#install +[autocomplete-image]: ../img/autocomplete.png \ No newline at end of file -- cgit v1.2.3 From 1cfb1cf45861e7dd20b5ef3eecb6c0402e15a82f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 10 Jul 2013 21:14:18 +0100 Subject: Added @cyroxx for work on #978 --- 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 42b28d26..38146327 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -146,6 +146,7 @@ The following people have helped make REST framework great. * Igor Kalat - [trwired] * Rudolf Olah - [omouse] * Gertjan Oude Lohuis - [gertjanol] +* Matthias Jacob - [cyroxx] Many thanks to everyone who's contributed to the project. @@ -328,3 +329,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [trwired]: https://github.com/trwired [omouse]: https://github.com/omouse [gertjanol]: https://github.com/gertjanol +[cyroxx]: https://github.com/cyroxx -- cgit v1.2.3 From 8f2e71a67fad17a0e44df6747ca450a101979c24 Mon Sep 17 00:00:00 2001 From: Kevin Brown Date: Fri, 19 Jul 2013 19:49:20 -0400 Subject: Modified documentation for CSRF as mentioned in #984 --- docs/topics/ajax-csrf-cors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/ajax-csrf-cors.md b/docs/topics/ajax-csrf-cors.md index 4566f38b..0555b84d 100644 --- a/docs/topics/ajax-csrf-cors.md +++ b/docs/topics/ajax-csrf-cors.md @@ -23,7 +23,7 @@ To guard against these type of attacks, you need to do two things: If you're using `SessionAuthentication` you'll need to include valid CSRF tokens for any `POST`, `PUT`, `PATCH` or `DELETE` operations. -The Django documentation describes how to [include CSRF tokens in AJAX requests][csrf-ajax]. +In order to make AJAX requests, you need to include CSRF token in the HTTP header, as [described in the Django documentation][csrf-ajax]. ## CORS -- cgit v1.2.3 From 61a242e27b483bb9570cc8eec2bc42a81ed09c45 Mon Sep 17 00:00:00 2001 From: Steve Date: Tue, 23 Jul 2013 10:40:54 -0400 Subject: added script block to list of blocks Phew, was afraid I wouldn't be able to overwrite this section..--- docs/topics/browsable-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index 895b3c5f..2ae8cadb 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -75,6 +75,7 @@ All of the blocks available in the browsable API base template that can be used * `branding` - 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. * `footer` - Any copyright notices or similar footer materials can go here (by default right-aligned). +* `script` - JavaScript files for the page. * `style` - CSS stylesheets for the page. * `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. @@ -170,4 +171,4 @@ You can now add the `autocomplete_light.ChoiceWidget` widget to the serializer f [autocomplete-packages]: https://www.djangopackages.com/grids/g/auto-complete/ [django-autocomplete-light]: https://github.com/yourlabs/django-autocomplete-light [django-autocomplete-light-install]: http://django-autocomplete-light.readthedocs.org/en/latest/#install -[autocomplete-image]: ../img/autocomplete.png \ No newline at end of file +[autocomplete-image]: ../img/autocomplete.png -- cgit v1.2.3 From c23412b51c5d8abbe1c103d7e177606644f9f0b7 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Wed, 24 Jul 2013 11:02:10 +0200 Subject: Add @pzinovkin for #995 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 38146327..f6b59ed4 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -147,6 +147,7 @@ The following people have helped make REST framework great. * Rudolf Olah - [omouse] * Gertjan Oude Lohuis - [gertjanol] * Matthias Jacob - [cyroxx] +* Pavel Zinovkin - [pzinovkin] Many thanks to everyone who's contributed to the project. @@ -330,3 +331,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [omouse]: https://github.com/omouse [gertjanol]: https://github.com/gertjanol [cyroxx]: https://github.com/cyroxx +[pzinovkin]: https://github.com/pzinovkin -- cgit v1.2.3 From 0fa9866848238ed355461a619e5aa9a148403f5f Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Fri, 26 Jul 2013 09:26:32 +0200 Subject: Add @willkg for #1007 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 f6b59ed4..dcd147e3 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -148,6 +148,7 @@ The following people have helped make REST framework great. * Gertjan Oude Lohuis - [gertjanol] * Matthias Jacob - [cyroxx] * Pavel Zinovkin - [pzinovkin] +* Will Kahn-Greene - [willkg] Many thanks to everyone who's contributed to the project. @@ -332,3 +333,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [gertjanol]: https://github.com/gertjanol [cyroxx]: https://github.com/cyroxx [pzinovkin]: https://github.com/pzinovkin +[willkg]: https://github.com/willkg -- cgit v1.2.3 From 9088c18da85bc56b363f5f1995159cc26e102254 Mon Sep 17 00:00:00 2001 From: Kevin Brown Date: Fri, 26 Jul 2013 11:03:37 -0400 Subject: Added to the credits --- 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 dcd147e3..f6e77996 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -149,6 +149,7 @@ The following people have helped make REST framework great. * Matthias Jacob - [cyroxx] * Pavel Zinovkin - [pzinovkin] * Will Kahn-Greene - [willkg] +* Kevin Brown - [kevin-brown] Many thanks to everyone who's contributed to the project. @@ -334,3 +335,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [cyroxx]: https://github.com/cyroxx [pzinovkin]: https://github.com/pzinovkin [willkg]: https://github.com/willkg +[kevin-brown]: https://github.com/kevin-brown -- cgit v1.2.3 From e98c229e5aa86f0da872583c08f353d974d9cc98 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Sun, 28 Jul 2013 18:51:22 +0200 Subject: Add @coderigo for #1011 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 f6e77996..95cac717 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -150,6 +150,7 @@ The following people have helped make REST framework great. * Pavel Zinovkin - [pzinovkin] * Will Kahn-Greene - [willkg] * Kevin Brown - [kevin-brown] +* Rodrigo Martell - [coderigo] Many thanks to everyone who's contributed to the project. @@ -334,5 +335,6 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [gertjanol]: https://github.com/gertjanol [cyroxx]: https://github.com/cyroxx [pzinovkin]: https://github.com/pzinovkin +[coderigo]: https://github.com/coderigo [willkg]: https://github.com/willkg [kevin-brown]: https://github.com/kevin-brown -- cgit v1.2.3 From 205c626d6ec472603207e12f8cf9deb3f00bf729 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Mon, 29 Jul 2013 15:53:26 +0200 Subject: Add @jimr for #1013 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 95cac717..4cc7f34b 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -151,6 +151,7 @@ The following people have helped make REST framework great. * Will Kahn-Greene - [willkg] * Kevin Brown - [kevin-brown] * Rodrigo Martell - [coderigo] +* James Rutherford - [jimr] Many thanks to everyone who's contributed to the project. @@ -338,3 +339,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [coderigo]: https://github.com/coderigo [willkg]: https://github.com/willkg [kevin-brown]: https://github.com/kevin-brown +[jimr]: https://github.com/jimr -- cgit v1.2.3 From 56d19dcc1c71494e83336a799ccf1f500a5af3b8 Mon Sep 17 00:00:00 2001 From: leandersikma Date: Tue, 30 Jul 2013 11:26:17 +0200 Subject: Wrong name of the login_base html file. Changed rest_framework/base_login.html to rest_framework/login_base.html (which is the correct name the user should extends in their templates).--- docs/topics/browsable-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/topics') diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index 2ae8cadb..b2c78f3c 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -90,7 +90,7 @@ The browsable API makes use of the Bootstrap tooltips component. Any element wi ### Login Template -To add branding and customize the look-and-feel of the login template, create a template called `login.html` and add it to your project, eg: `templates/rest_framework/login.html`. The template should extend from `rest_framework/base_login.html`. +To add branding and customize the look-and-feel of the login template, create a template called `login.html` and add it to your project, eg: `templates/rest_framework/login.html`. The template should extend from `rest_framework/login_base.html`. You can add your site name or branding by including the branding block: -- cgit v1.2.3 From e4144b5b674cc8849c248727a09b82b82d1a01c9 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Fri, 2 Aug 2013 08:59:18 +0200 Subject: Add @rlr for #1022 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 4cc7f34b..d1fa3681 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -152,6 +152,7 @@ The following people have helped make REST framework great. * Kevin Brown - [kevin-brown] * Rodrigo Martell - [coderigo] * James Rutherford - [jimr] +* ricky rosario - [rlr] Many thanks to everyone who's contributed to the project. @@ -340,3 +341,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [willkg]: https://github.com/willkg [kevin-brown]: https://github.com/kevin-brown [jimr]: https://github.com/jimr +[rlr]: https://github.com/rlr -- cgit v1.2.3 From 4d8d2340be4de905af3488dc721c7b94b1371ef0 Mon Sep 17 00:00:00 2001 From: Veronica Lynn Date: Wed, 7 Aug 2013 14:00:06 -0400 Subject: Fixed typos in a bunch of docs --- docs/topics/2.2-announcement.md | 6 +++--- docs/topics/2.3-announcement.md | 12 ++++++------ docs/topics/documenting-your-api.md | 8 ++++---- 3 files changed, 13 insertions(+), 13 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/2.2-announcement.md b/docs/topics/2.2-announcement.md index 02cac129..7d276049 100644 --- a/docs/topics/2.2-announcement.md +++ b/docs/topics/2.2-announcement.md @@ -136,15 +136,15 @@ Now becomes: def has_object_permission(self, request, view, obj): return obj.owner == request.user -If you're overriding the `BasePermission` class, the old-style signature will continue to function, and will correctly handle both global and object-level permissions checks, but it's use will raise a `PendingDeprecationWarning`. +If you're overriding the `BasePermission` class, the old-style signature will continue to function, and will correctly handle both global and object-level permissions checks, but its use will raise a `PendingDeprecationWarning`. Note also that the usage of the internal APIs for permission checking on the `View` class has been cleaned up slightly, and is now documented and subject to the deprecation policy in all future versions. ### More explicit hyperlink relations behavior -When using a serializer with a `HyperlinkedRelatedField` or `HyperlinkedIdentityField`, the hyperlinks would previously use absolute URLs if the serializer context included a `'request'` key, and fallback to using relative URLs otherwise. This could lead to non-obvious behavior, as it might not be clear why some serializers generated absolute URLs, and others do not. +When using a serializer with a `HyperlinkedRelatedField` or `HyperlinkedIdentityField`, the hyperlinks would previously use absolute URLs if the serializer context included a `'request'` key, and fall back to using relative URLs otherwise. This could lead to non-obvious behavior, as it might not be clear why some serializers generated absolute URLs, and others do not. -From version 2.2 onwards, serializers with hyperlinked relationships *always* require a `'request'` key to be supplied in the context dictionary. The implicit behavior will continue to function, but it's use will raise a `PendingDeprecationWarning`. +From version 2.2 onwards, serializers with hyperlinked relationships *always* require a `'request'` key to be supplied in the context dictionary. The implicit behavior will continue to function, but its use will raise a `PendingDeprecationWarning`. [xordoquy]: https://github.com/xordoquy [django-python-3]: https://docs.djangoproject.com/en/dev/faq/install/#can-i-use-django-with-python-3 diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md index 9fdebcd9..ba435145 100644 --- a/docs/topics/2.3-announcement.md +++ b/docs/topics/2.3-announcement.md @@ -131,7 +131,7 @@ The `get_object` and `get_paginate_by` methods no longer take an optional querys Using an optional queryset with these methods continues to be supported, but will raise a `PendingDeprecationWarning`. -The `paginate_queryset` method no longer takes a `page_size` argument, or returns a four-tuple of pagination information. Instead it simply takes a queryset argument, and either returns a `page` object with an appropraite page size, or returns `None`, if pagination is not configured for the view. +The `paginate_queryset` method no longer takes a `page_size` argument, or returns a four-tuple of pagination information. Instead it simply takes a queryset argument, and either returns a `page` object with an appropriate page size, or returns `None`, if pagination is not configured for the view. Using the `page_size` argument is still supported and will trigger the old-style return type, but will raise a `PendingDeprecationWarning`. @@ -195,13 +195,13 @@ Usage of the old-style attributes continues to be supported, but will raise a `P 2.3 introduces a `DecimalField` serializer field, which returns `Decimal` instances. -For most cases APIs using model fields will behave as previously, however if you are using a custom renderer, not provided by REST framework, then you may now need to add support for rendering `Decimal` instances to your renderer implmentation. +For most cases APIs using model fields will behave as previously, however if you are using a custom renderer, not provided by REST framework, then you may now need to add support for rendering `Decimal` instances to your renderer implementation. ## ModelSerializers and reverse relationships The support for adding reverse relationships to the `fields` option on a `ModelSerializer` class means that the `get_related_field` and `get_nested_field` method signatures have now changed. -In the unlikely event that you're providing a custom serializer class, and implementing these methods you should note the new call signature for both methods is now `(self, model_field, related_model, to_many)`. For revese relationships `model_field` will be `None`. +In the unlikely event that you're providing a custom serializer class, and implementing these methods you should note the new call signature for both methods is now `(self, model_field, related_model, to_many)`. For reverse relationships `model_field` will be `None`. The old-style signature will continue to function but will raise a `PendingDeprecationWarning`. @@ -219,7 +219,7 @@ Note that the relevant methods have always been private APIs, and the docstrings ## More explicit style -The usage of `model` attribute in generic Views is still supported, but it's usage is generally being discouraged throughout the documentation, in favour of the setting the more explict `queryset` and `serializer_class` attributes. +The usage of `model` attribute in generic Views is still supported, but it's usage is generally being discouraged throughout the documentation, in favour of the setting the more explicit `queryset` and `serializer_class` attributes. For example, the following is now the recommended style for using generic views: @@ -227,7 +227,7 @@ For example, the following is now the recommended style for using generic views: queryset = MyModel.objects.all() serializer_class = MyModelSerializer -Using an explict `queryset` and `serializer_class` attributes makes the functioning of the view more clear than using the shortcut `model` attribute. +Using an explicit `queryset` and `serializer_class` attributes makes the functioning of the view more clear than using the shortcut `model` attribute. It also makes the usage of the `get_queryset()` or `get_serializer_class()` methods more obvious. @@ -246,7 +246,7 @@ It also makes the usage of the `get_queryset()` or `get_serializer_class()` meth ## Django 1.3 support -The 2.3.x release series will be the last series to provide compatiblity with Django 1.3. +The 2.3.x release series will be the last series to provide compatibility with Django 1.3. ## Version 2.2 API changes diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index 7ee538f5..6291c924 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -16,7 +16,7 @@ The most common way to document Web APIs today is to produce documentation that Marc Gibbons' [Django REST Swagger][django-rest-swagger] integrates REST framework with the [Swagger][swagger] API documentation tool. The package produces well presented API documentation, and includes interactive tools for testing API endpoints. -The pacakge is fully documented, well supported, and comes highly recommended. +The package is fully documented, well supported, and comes highly recommended. Django REST Swagger supports REST framework versions 2.3 and above. @@ -42,7 +42,7 @@ There are various other online tools and services for providing API documentatio ## Self describing APIs -The browsable API that REST framwork provides makes it possible for your API to be entirely self describing. The documentation for each API endpoint can be provided simply by visiting the URL in your browser. +The browsable API that REST framework provides makes it possible for your API to be entirely self describing. The documentation for each API endpoint can be provided simply by visiting the URL in your browser. ![Screenshot - Self describing API][image-self-describing-api] @@ -93,11 +93,11 @@ You can modify the response behavior to `OPTIONS` requests by overriding the `me ## The hypermedia approach -To be fully RESTful an API should present it's available actions as hypermedia controls in the responses that it sends. +To be fully RESTful an API should present its available actions as hypermedia controls in the responses that it sends. In this approach, rather than documenting the available API endpoints up front, the description instead concentrates on the *media types* that are used. The available actions take may be taken on any given URL are not strictly fixed, but are instead made available by the presence of link and form controls in the returned document. -To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type. The [REST, Hypermedia & HATEOAS][hypermedia-docs] section of the documention includes pointers to background reading, as well as links to various hypermedia formats. +To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type. The [REST, Hypermedia & HATEOAS][hypermedia-docs] section of the documentation includes pointers to background reading, as well as links to various hypermedia formats. [cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven [django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger -- cgit v1.2.3 From 2761d6a4724d3dc60f817ab0718446564ca62f80 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 7 Aug 2013 20:27:41 +0100 Subject: Added @kolvia. For multiple documentation fixes in #1026. Thank you! :)--- 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 d1fa3681..855ee479 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -152,7 +152,8 @@ The following people have helped make REST framework great. * Kevin Brown - [kevin-brown] * Rodrigo Martell - [coderigo] * James Rutherford - [jimr] -* ricky rosario - [rlr] +* Ricky Rosario - [rlr] +* Veronica Lynn - [kolvia] Many thanks to everyone who's contributed to the project. @@ -342,3 +343,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [kevin-brown]: https://github.com/kevin-brown [jimr]: https://github.com/jimr [rlr]: https://github.com/rlr +[kolvia]: https://github.com/kolvia -- cgit v1.2.3 From 54b7b6760c40d9820268207a44996e2118430744 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 12 Aug 2013 09:27:34 +0100 Subject: Added @etos. For fixes in #1029, #1030 - 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 855ee479..c563971c 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -154,6 +154,7 @@ The following people have helped make REST framework great. * James Rutherford - [jimr] * Ricky Rosario - [rlr] * Veronica Lynn - [kolvia] +* Dan Stephenson - [etos] Many thanks to everyone who's contributed to the project. @@ -344,3 +345,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [jimr]: https://github.com/jimr [rlr]: https://github.com/rlr [kolvia]: https://github.com/kolvia +[etos]: https://github.com/etos -- cgit v1.2.3 From 999056cde1c6355d5ca036f109b35b41cb9d47cc Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Tue, 13 Aug 2013 10:43:07 +0200 Subject: Add @martync for #1033 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 c563971c..b91f051b 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -155,6 +155,7 @@ The following people have helped make REST framework great. * Ricky Rosario - [rlr] * Veronica Lynn - [kolvia] * Dan Stephenson - [etos] +* Martin Clement - [martync] Many thanks to everyone who's contributed to the project. @@ -346,3 +347,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [rlr]: https://github.com/rlr [kolvia]: https://github.com/kolvia [etos]: https://github.com/etos +[martync]: https://github.com/martync -- cgit v1.2.3 From 7bc63fbb11525c37fa73e1ffa9a6409a48aab4ac Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 14 Aug 2013 13:17:30 +0100 Subject: Added @jsatt. For fix & tests in #1037.--- 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 b91f051b..1b34d5e0 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -156,6 +156,7 @@ The following people have helped make REST framework great. * Veronica Lynn - [kolvia] * Dan Stephenson - [etos] * Martin Clement - [martync] +* Jeremy Satterfield - [jsatt] Many thanks to everyone who's contributed to the project. @@ -348,3 +349,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [kolvia]: https://github.com/kolvia [etos]: https://github.com/etos [martync]: https://github.com/martync +[jsatt]: https://github.com/jsatt -- cgit v1.2.3 From d5b56310b0cc99df1cd1e61fc35f251c46036d62 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Aug 2013 13:23:27 +0100 Subject: Update release notes --- docs/topics/release-notes.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/topics') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index d379ab74..876f46d8 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -40,6 +40,17 @@ You can determine your currently installed version using `pip freeze`: ## 2.3.x series +### master + +* Added `APITestClient`, `APIRequestFactory` and `APITestCase` etc... +* Refactor `SessionAuthentication` to allow esier override for CSRF exemption. +* Remove 'Hold down "Control" message from help_text". +* Added admin configuration for tokens. +* Bugfix: `AnonRateThrottle` fixed to not throttle authenticated users. +* Bugfix: Don't set `X-Throttle-Wait-Seconds` when throttle does not have `wait` value. +* Bugfix: Fixed `PATCH` button title in browsable API. +* Bugfix: Fix issue with OAuth2 provider naive datetimes. + ### 2.3.6 **Date**: 27th June 2013 -- cgit v1.2.3 From f6f69dc71d4db7492b5feecc69627dff0031e2b9 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Aug 2013 14:03:20 +0100 Subject: Version 2.3.7 --- docs/topics/release-notes.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/topics') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 876f46d8..624d9acd 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -40,12 +40,14 @@ You can determine your currently installed version using `pip freeze`: ## 2.3.x series -### master +### 2.3.7 + +**Date**: 16th August 2013 * Added `APITestClient`, `APIRequestFactory` and `APITestCase` etc... * Refactor `SessionAuthentication` to allow esier override for CSRF exemption. -* Remove 'Hold down "Control" message from help_text". -* Added admin configuration for tokens. +* Remove 'Hold down "Control" message from help_text' widget messaging when not appropriate. +* Added admin configuration for auth tokens. * Bugfix: `AnonRateThrottle` fixed to not throttle authenticated users. * Bugfix: Don't set `X-Throttle-Wait-Seconds` when throttle does not have `wait` value. * Bugfix: Fixed `PATCH` button title in browsable API. -- cgit v1.2.3 From 3a99b0af5074bfae90ec3986f277720df5a13583 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 19 Aug 2013 08:47:52 +0100 Subject: Added @chrispaolini. For customizable view names/descriptions in #1043. 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 1b34d5e0..e9b60074 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -157,6 +157,7 @@ The following people have helped make REST framework great. * Dan Stephenson - [etos] * Martin Clement - [martync] * Jeremy Satterfield - [jsatt] +* Christopher Paolini - [chrispaolini] Many thanks to everyone who's contributed to the project. @@ -350,3 +351,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [etos]: https://github.com/etos [martync]: https://github.com/martync [jsatt]: https://github.com/jsatt +[chrispaolini]: https://github.com/chrispaolini -- cgit v1.2.3 From 34d65119fc1c200b76a8af7213a92d6b279bd478 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 19 Aug 2013 08:54:48 +0100 Subject: Update release notes. --- docs/topics/release-notes.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/topics') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 624d9acd..52abfc08 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -40,6 +40,10 @@ You can determine your currently installed version using `pip freeze`: ## 2.3.x series +### Master + +* Support customizable view name and description functions, using the `VIEW_NAME_FUNCTION` and `VIEW_DESCRIPTION_FUNCTION` settings. + ### 2.3.7 **Date**: 16th August 2013 -- cgit v1.2.3