diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api-guide/authentication.md | 6 | ||||
| -rw-r--r-- | docs/api-guide/fields.md | 42 | ||||
| -rw-r--r-- | docs/api-guide/throttling.md | 6 | ||||
| -rw-r--r-- | docs/index.md | 2 | ||||
| -rw-r--r-- | docs/template.html | 2 | ||||
| -rw-r--r-- | docs/topics/credits.md | 10 | ||||
| -rw-r--r-- | docs/topics/release-notes.md | 22 | ||||
| -rw-r--r-- | docs/tutorial/3-class-based-views.md | 4 | ||||
| -rw-r--r-- | docs/tutorial/quickstart.md | 9 |
9 files changed, 71 insertions, 32 deletions
diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 889d16c0..3137b9d4 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -30,7 +30,7 @@ The default authentication policy may be set globally, using the `DEFAULT_AUTHEN REST_FRAMEWORK = { 'DEFAULT_AUTHENTICATION_CLASSES': ( - 'rest_framework.authentication.UserBasicAuthentication', + 'rest_framework.authentication.BasicAuthentication', 'rest_framework.authentication.SessionAuthentication', ) } @@ -38,7 +38,7 @@ The default authentication policy may be set globally, using the `DEFAULT_AUTHEN You can also set the authentication policy on a per-view basis, using the `APIView` class based views. class ExampleView(APIView): - authentication_classes = (SessionAuthentication, UserBasicAuthentication) + authentication_classes = (SessionAuthentication, BasicAuthentication) permission_classes = (IsAuthenticated,) def get(self, request, format=None): @@ -51,7 +51,7 @@ You can also set the authentication policy on a per-view basis, using the `APIVi Or, if you're using the `@api_view` decorator with function based views. @api_view(['GET']) - @authentication_classes((SessionAuthentication, UserBasicAuthentication)) + @authentication_classes((SessionAuthentication, BasicAuthentication)) @permissions_classes((IsAuthenticated,)) def example_view(request, format=None): content = { diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 8c3df067..86460b4b 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -235,44 +235,48 @@ Then an example output format for a Bookmark instance would be: 'url': u'https://www.djangoproject.com/' } -## PrimaryKeyRelatedField +## PrimaryKeyRelatedField / ManyPrimaryKeyRelatedField -This field can be applied to any "to-one" relationship, such as a `ForeignKey` field. +`PrimaryKeyRelatedField` and `ManyPrimaryKeyRelatedField` will represent the target of the relationship using it's primary key. -`PrimaryKeyRelatedField` will represent the target of the field using it's primary key. +Be default these fields read-write, although you can change this behaviour using the `read_only` flag. -Be default, `PrimaryKeyRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +**Arguments**: -## ManyPrimaryKeyRelatedField +* `queryset` - All relational fields must either set a queryset, or set `read_only=True` -This field can be applied to any "to-many" relationship, such as a `ManyToManyField` field, or a reverse `ForeignKey` relationship. +## SlugRelatedField / ManySlugRelatedField -`PrimaryKeyRelatedField` will represent the targets of the field using their primary key. +`SlugRelatedField` and `ManySlugRelatedField` will represent the target of the relationship using a unique slug. -Be default, `ManyPrimaryKeyRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +Be default these fields read-write, although you can change this behaviour using the `read_only` flag. -## HyperlinkedRelatedField +**Arguments**: -This field can be applied to any "to-one" relationship, such as a `ForeignKey` field. +* `slug_field` - The field on the target that should used as the representation. This should be a field that uniquely identifies any given instance. For example, `username`. +* `queryset` - All relational fields must either set a queryset, or set `read_only=True` -`HyperlinkedRelatedField` will represent the target of the field using a hyperlink. You must include a named URL pattern in your URL conf, with a name like `'{model-name}-detail'` that corresponds to the target of the hyperlink. +## HyperlinkedRelatedField / ManyHyperlinkedRelatedField -Be default, `HyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. - -## ManyHyperlinkedRelatedField +`HyperlinkedRelatedField` and `ManyHyperlinkedRelatedField` will represent the target of the relationship using a hyperlink. -This field can be applied to any "to-many" relationship, such as a `ManyToManyField` field, or a reverse `ForeignKey` relationship. +Be default, `HyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. -`ManyHyperlinkedRelatedField` will represent the targets of the field using hyperlinks. You must include a named URL pattern in your URL conf, with a name like `'{model-name}-detail'` that corresponds to the target of the hyperlink. +**Arguments**: -Be default, `ManyHyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +* `view_name` - The view name that should be used as the target of the relationship. **required**. +* `format` - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the `format` argument. +* `queryset` - All relational fields must either set a queryset, or set `read_only=True` ## HyperLinkedIdentityField This field can be applied as an identity relationship, such as the `'url'` field on a HyperlinkedModelSerializer. -You must include a named URL pattern in your URL conf, with a name like `'{model-name}-detail'` that corresponds to the model. - This field is always read-only. +**Arguments**: + +* `view_name` - The view name that should be used as the target of the relationship. **required**. +* `format` - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the `format` argument. + [cite]: http://www.python.org/dev/peps/pep-0020/ diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index bfda7079..b03bc9e0 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -31,8 +31,8 @@ The default throttling policy may be set globally, using the `DEFAULT_THROTTLE_C REST_FRAMEWORK = { 'DEFAULT_THROTTLE_CLASSES': ( - 'rest_framework.throttles.AnonThrottle', - 'rest_framework.throttles.UserThrottle' + 'rest_framework.throttling.AnonRateThrottle', + 'rest_framework.throttling.UserRateThrottle' ), 'DEFAULT_THROTTLE_RATES': { 'anon': '100/day', @@ -136,7 +136,7 @@ For example, given the following views... REST_FRAMEWORK = { 'DEFAULT_THROTTLE_CLASSES': ( - 'rest_framework.throttles.ScopedRateThrottle' + 'rest_framework.throttling.ScopedRateThrottle' ), 'DEFAULT_THROTTLE_RATES': { 'contacts': '1000/day', diff --git a/docs/index.md b/docs/index.md index 75a1cf6e..5e086872 100644 --- a/docs/index.md +++ b/docs/index.md @@ -66,11 +66,9 @@ If you're intending to use the browseable API you'll want to add REST framework' Note that the URL path can be whatever you want, but you must include `rest_framework.urls` with the `rest_framework` namespace. -<!-- ## Quickstart Can't wait to get started? The [quickstart guide][quickstart] is the fastest way to get up and running with REST framework. ---> ## Tutorial diff --git a/docs/template.html b/docs/template.html index 94fc269f..c428dff3 100644 --- a/docs/template.html +++ b/docs/template.html @@ -53,7 +53,7 @@ <li class="dropdown"> <a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a> <ul class="dropdown-menu"> - <!--<li><a href="{{ base_url }}/tutorial/quickstart{{ suffix }}">Quickstart</a></li>--> + <li><a href="{{ base_url }}/tutorial/quickstart{{ suffix }}">Quickstart</a></li> <li><a href="{{ base_url }}/tutorial/1-serialization{{ suffix }}">1 - Serialization</a></li> <li><a href="{{ base_url }}/tutorial/2-requests-and-responses{{ suffix }}">2 - Requests and responses</a></li> <li><a href="{{ base_url }}/tutorial/3-class-based-views{{ suffix }}">3 - Class based views</a></li> diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 69d57802..ee00fc8b 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -51,6 +51,10 @@ The following people have helped make REST framework great. * Daniel Vaca Araujo - [diviei] * Madis Väin - [madisvain] * Stephan Groß - [minddust] +* Pavel Savchenko - [asfaltboy] +* Otto Yiu - [ottoyiu] +* Jacob Magnusson - [jmagnusson] +* Osiloke Harold Emoekpere - [osiloke] Many thanks to everyone who's contributed to the project. @@ -136,4 +140,8 @@ To contact the author directly: [rdobson]: https://github.com/rdobson [diviei]: https://github.com/diviei [madisvain]: https://github.com/madisvain -[minddust]: https://github.com/minddust
\ No newline at end of file +[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 diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index a466f4b1..14d910bd 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -4,8 +4,30 @@ > > — Eric S. Raymond, [The Cathedral and the Bazaar][cite]. +## Master + +* Support Django's cache framework. +* Minor field improvements. (Don't stringify dicts, more robust many-pk fields.) +* Bugfixes (Support choice field in Browseable API) + +## 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]. diff --git a/docs/tutorial/3-class-based-views.md b/docs/tutorial/3-class-based-views.md index a31dccb2..91ef4038 100644 --- a/docs/tutorial/3-class-based-views.md +++ b/docs/tutorial/3-class-based-views.md @@ -92,7 +92,7 @@ Let's take a look at how we can compose our views by using the mixin classes. class SnippetList(mixins.ListModelMixin, mixins.CreateModelMixin, - generics.MultipleObjectBaseView): + generics.MultipleObjectAPIView): model = Snippet serializer_class = SnippetSerializer @@ -102,7 +102,7 @@ Let's take a look at how we can compose our views by using the mixin classes. def post(self, request, *args, **kwargs): return self.create(request, *args, **kwargs) -We'll take a moment to examine exactly what's happening here - We're building our view using `MultipleObjectBaseView`, and adding in `ListModelMixin` and `CreateModelMixin`. +We'll take a moment to examine exactly what's happening here - We're building our view using `MultipleObjectAPIView`, and adding in `ListModelMixin` and `CreateModelMixin`. The base class provides the core functionality, and the mixin classes provide the `.list()` and `.create()` actions. We're then explicitly binding the `get` and `post` methods to the appropriate actions. Simple enough stuff so far. diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 6bde725b..93da1a59 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -19,12 +19,19 @@ First up we're going to define some serializers in `quickstart/serializers.py` t class GroupSerializer(serializers.HyperlinkedModelSerializer): + permissions = serializers.ManySlugRelatedField( + slug_field='codename', + queryset=Permission.objects.all() + ) + class Meta: model = Group fields = ('url', 'name', 'permissions') Notice that we're using hyperlinked relations in this case, with `HyperlinkedModelSerializer`. You can also use primary key and various other relationships, but hyperlinking is good RESTful design. +We've also overridden the `permission` field on the `GroupSerializer`. In this case we don't want to use a hyperlinked representation, but instead use the list of permission codenames associated with the group, so we've used a `ManySlugRelatedField`, using the `codename` field for the representation. + ## Views Right, we'd better write some views then. Open `quickstart/views.py` and get typing. @@ -152,7 +159,7 @@ We can now access our API, both from the command-line, using tools like `curl`.. }, { "email": "tom@example.com", - "groups": [], + "groups": [ ], "url": "http://127.0.0.1:8000/users/2/", "username": "tom" } |