mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-11-10 19:56:59 +03:00
Fixed typos in a bunch of docs
This commit is contained in:
parent
b52beb0734
commit
4d8d2340be
|
@ -147,7 +147,7 @@ If you need to test if a request is a read operation or a write operation, you s
|
|||
|
||||
**Note**: In versions 2.0 and 2.1, the signature for the permission checks always included an optional `obj` parameter, like so: `.has_permission(self, request, view, obj=None)`. The method would be called twice, first for the global permission checks, with no object supplied, and second for the object-level check when required.
|
||||
|
||||
As of version 2.2 this signature has now been replaced with two separate method calls, which is more explict and obvious. The old style signature continues to work, but it's use will result in a `PendingDeprecationWarning`, which is silent by default. In 2.3 this will be escalated to a `DeprecationWarning`, and in 2.4 the old-style signature will be removed.
|
||||
As of version 2.2 this signature has now been replaced with two separate method calls, which is more explicit and obvious. The old style signature continues to work, but its use will result in a `PendingDeprecationWarning`, which is silent by default. In 2.3 this will be escalated to a `DeprecationWarning`, and in 2.4 the old-style signature will be removed.
|
||||
|
||||
For more details see the [2.2 release announcement][2.2-announcement].
|
||||
|
||||
|
|
|
@ -39,7 +39,7 @@ In order to explain the various types of relational fields, we'll use a couple o
|
|||
|
||||
## RelatedField
|
||||
|
||||
`RelatedField` may be used to represent the target of the relationship using it's `__unicode__` method.
|
||||
`RelatedField` may be used to represent the target of the relationship using its `__unicode__` method.
|
||||
|
||||
For example, the following serializer.
|
||||
|
||||
|
@ -71,7 +71,7 @@ This field is read only.
|
|||
|
||||
## PrimaryKeyRelatedField
|
||||
|
||||
`PrimaryKeyRelatedField` may be used to represent the target of the relationship using it's primary key.
|
||||
`PrimaryKeyRelatedField` may be used to represent the target of the relationship using its primary key.
|
||||
|
||||
For example, the following serializer:
|
||||
|
||||
|
@ -252,7 +252,7 @@ If you want to implement a read-write relational field, you must also implement
|
|||
|
||||
## Example
|
||||
|
||||
For, example, we could define a relational field, to serialize a track to a custom string representation, using it's ordering, title, and duration.
|
||||
For, example, we could define a relational field, to serialize a track to a custom string representation, using its ordering, title, and duration.
|
||||
|
||||
import time
|
||||
|
||||
|
@ -386,7 +386,7 @@ For more information see [the Django documentation on generic relations][generic
|
|||
By default, relational fields that target a ``ManyToManyField`` with a
|
||||
``through`` model specified are set to read-only.
|
||||
|
||||
If you exlicitly specify a relational field pointing to a
|
||||
If you explicitly specify a relational field pointing to a
|
||||
``ManyToManyField`` with a through model, be sure to set ``read_only``
|
||||
to ``True``.
|
||||
|
||||
|
|
|
@ -241,7 +241,7 @@ This renderer is used for rendering HTML multipart form data. **It is not suita
|
|||
|
||||
To implement a custom renderer, you should override `BaseRenderer`, set the `.media_type` and `.format` properties, and implement the `.render(self, data, media_type=None, renderer_context=None)` method.
|
||||
|
||||
The method should return a bytestring, which wil be used as the body of the HTTP response.
|
||||
The method should return a bytestring, which will be used as the body of the HTTP response.
|
||||
|
||||
The arguments passed to the `.render()` method are:
|
||||
|
||||
|
|
|
@ -24,7 +24,7 @@ Unless you want to heavily customize REST framework for some reason, you should
|
|||
|
||||
Unlike regular `HttpResponse` objects, you do not instantiate `Response` objects with rendered content. Instead you pass in unrendered data, which may consist of any Python primitives.
|
||||
|
||||
The renderers used by the `Response` class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primative datatypes before creating the `Response` object.
|
||||
The renderers used by the `Response` class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primitive datatypes before creating the `Response` object.
|
||||
|
||||
You can use REST framework's `Serializer` classes to perform this data serialization, or use your own custom serialization.
|
||||
|
||||
|
@ -54,7 +54,7 @@ The rendered content of the response. The `.render()` method must have been cal
|
|||
|
||||
## .template_name
|
||||
|
||||
The `template_name`, if supplied. Only required if `HTMLRenderer` or some other custom template renderer is the accepted renderer for the reponse.
|
||||
The `template_name`, if supplied. Only required if `HTMLRenderer` or some other custom template renderer is the accepted renderer for the response.
|
||||
|
||||
## .accepted_renderer
|
||||
|
||||
|
|
|
@ -17,7 +17,7 @@ The advantages of doing so are:
|
|||
|
||||
REST framework provides two utility functions to make it more simple to return absolute URIs from your Web API.
|
||||
|
||||
There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink it's output for you, which makes browsing the API much easier.
|
||||
There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink its output for you, which makes browsing the API much easier.
|
||||
|
||||
## reverse
|
||||
|
||||
|
|
|
@ -96,7 +96,7 @@ As with `SimpleRouter` the trailing slashes on the URL routes can be removed by
|
|||
|
||||
# Custom Routers
|
||||
|
||||
Implementing a custom router isn't something you'd need to do very often, but it can be useful if you have specific requirements about how the your URLs for your API are strutured. Doing so allows you to encapsulate the URL structure in a reusable way that ensures you don't have to write your URL patterns explicitly for each new view.
|
||||
Implementing a custom router isn't something you'd need to do very often, but it can be useful if you have specific requirements about how the your URLs for your API are structured. Doing so allows you to encapsulate the URL structure in a reusable way that ensures you don't have to write your URL patterns explicitly for each new view.
|
||||
|
||||
The simplest way to implement a custom router is to subclass one of the existing router classes. The `.routes` attribute is used to template the URL patterns that will be mapped to each viewset. The `.routes` attribute is a list of `Route` named tuples.
|
||||
|
||||
|
|
|
@ -403,7 +403,7 @@ You can change the field that is used for object lookups by setting the `lookup_
|
|||
|
||||
Not that the `lookup_field` will be used as the default on *all* hyperlinked fields, including both the URL identity, and any hyperlinked relationships.
|
||||
|
||||
For more specfic requirements such as specifying a different lookup for each field, you'll want to set the fields on the serializer explicitly. For example:
|
||||
For more specific requirements such as specifying a different lookup for each field, you'll want to set the fields on the serializer explicitly. For example:
|
||||
|
||||
class AccountSerializer(serializers.HyperlinkedModelSerializer):
|
||||
url = serializers.HyperlinkedIdentityField(
|
||||
|
@ -429,7 +429,7 @@ You can create customized subclasses of `ModelSerializer` or `HyperlinkedModelSe
|
|||
|
||||
Doing so should be considered advanced usage, and will only be needed if you have some particular serializer requirements that you often need to repeat.
|
||||
|
||||
## Dynamically modifiying fields
|
||||
## Dynamically modifying fields
|
||||
|
||||
Once a serializer has been initialized, the dictionary of fields that are set on the serializer may be accessed using the `.fields` attribute. Accessing and modifying this attribute allows you to dynamically modify the serializer.
|
||||
|
||||
|
@ -449,7 +449,7 @@ For example, if you wanted to be able to set which fields should be used by a se
|
|||
# Don't pass the 'fields' arg up to the superclass
|
||||
fields = kwargs.pop('fields', None)
|
||||
|
||||
# Instatiate the superclass normally
|
||||
# Instantiate the superclass normally
|
||||
super(DynamicFieldsModelSerializer, self).__init__(*args, **kwargs)
|
||||
|
||||
if fields:
|
||||
|
|
|
@ -28,7 +28,7 @@ you should use the `api_settings` object. For example.
|
|||
|
||||
print api_settings.DEFAULT_AUTHENTICATION_CLASSES
|
||||
|
||||
The `api_settings` object will check for any user-defined settings, and otherwise fallback to the default values. Any setting that uses string import paths to refer to a class will automatically import and return the referenced class, instead of the string literal.
|
||||
The `api_settings` object will check for any user-defined settings, and otherwise fall back to the default values. Any setting that uses string import paths to refer to a class will automatically import and return the referenced class, instead of the string literal.
|
||||
|
||||
---
|
||||
|
||||
|
@ -165,7 +165,7 @@ Default: `'multipart'`
|
|||
|
||||
The renderer classes that are supported when building test requests.
|
||||
|
||||
The format of any of these renderer classes may be used when contructing a test request, for example: `client.post('/users', {'username': 'jamie'}, format='json')`
|
||||
The format of any of these renderer classes may be used when constructing a test request, for example: `client.post('/users', {'username': 'jamie'}, format='json')`
|
||||
|
||||
Default:
|
||||
|
||||
|
|
|
@ -34,7 +34,7 @@ To support a wider set of request formats, or change the default format, [see th
|
|||
|
||||
#### Explicitly encoding the request body
|
||||
|
||||
If you need to explictly encode the request body, you can do so by setting the `content_type` flag. For example:
|
||||
If you need to explicitly encode the request body, you can do so by setting the `content_type` flag. For example:
|
||||
|
||||
request = factory.post('/notes/', json.dumps({'title': 'new idea'}), content_type='application/json')
|
||||
|
||||
|
|
|
@ -110,7 +110,7 @@ You won't typically need to override this method.
|
|||
|
||||
### .finalize_response(self, request, response, \*args, **kwargs)
|
||||
|
||||
Ensures that any `Response` object returned from the handler method will be rendered into the correct content type, as determined by the content negotation.
|
||||
Ensures that any `Response` object returned from the handler method will be rendered into the correct content type, as determined by the content negotiation.
|
||||
|
||||
You won't typically need to override this method.
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -236,7 +236,7 @@ Edit the `snippet/views.py` file, and add the following.
|
|||
|
||||
class JSONResponse(HttpResponse):
|
||||
"""
|
||||
An HttpResponse that renders it's content into JSON.
|
||||
An HttpResponse that renders its content into JSON.
|
||||
"""
|
||||
def __init__(self, data, **kwargs):
|
||||
content = JSONRenderer().render(data)
|
||||
|
|
|
@ -81,7 +81,7 @@ Okay, we're done. If you run the development server everything should be workin
|
|||
|
||||
One of the big wins of using class based views is that it allows us to easily compose reusable bits of behaviour.
|
||||
|
||||
The create/retrieve/update/delete operations that we've been using so far are going to be pretty simliar for any model-backed API views we create. Those bits of common behaviour are implemented in REST framework's mixin classes.
|
||||
The create/retrieve/update/delete operations that we've been using so far are going to be pretty similar for any model-backed API views we create. Those bits of common behaviour are implemented in REST framework's mixin classes.
|
||||
|
||||
Let's take a look at how we can compose our views by using the mixin classes.
|
||||
|
||||
|
|
Loading…
Reference in New Issue
Block a user