mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-11-29 13:04:03 +03:00
Fixing spelling errors.
This commit is contained in:
parent
efabd2bb1b
commit
71a93930fd
|
@ -86,7 +86,7 @@ You'll also need to create tokens for your users.
|
|||
token = Token.objects.create(user=...)
|
||||
print token.key
|
||||
|
||||
For clients to authenticate, the token key should be included in the `Authorization` HTTP header. The key should be prefixed by the string literal "Token", with whitespace seperating the two strings. For example:
|
||||
For clients to authenticate, the token key should be included in the `Authorization` HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example:
|
||||
|
||||
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
|
||||
|
||||
|
|
|
@ -12,7 +12,7 @@ Content negotiation is the process of selecting one of multiple possible represe
|
|||
|
||||
## Determining the accepted renderer
|
||||
|
||||
REST framework uses a simple style of content negotition to determine which media type should be returned to a client, based on the available renderers, the priorities of each of those renderers, and the client's `Accept:` header. The style used is partly client-driven, and partly server-driven.
|
||||
REST framework uses a simple style of content negotiation to determine which media type should be returned to a client, based on the available renderers, the priorities of each of those renderers, and the client's `Accept:` header. The style used is partly client-driven, and partly server-driven.
|
||||
|
||||
1. More specific media types are given preference to less specific media types.
|
||||
2. If multiple media types have the same specificity, then preference is given to based on the ordering of the renderers configured for the given view.
|
||||
|
@ -41,9 +41,9 @@ This is a valid approach as the HTTP spec deliberately underspecifies how a serv
|
|||
|
||||
# Custom content negotiation
|
||||
|
||||
It's unlikley that you'll want to provide a custom content negotiation scheme for REST framework, but you can do so if needed. To implement a custom content negotiation scheme override `BaseContentNegotiation`.
|
||||
It's unlikely that you'll want to provide a custom content negotiation scheme for REST framework, but you can do so if needed. To implement a custom content negotiation scheme override `BaseContentNegotiation`.
|
||||
|
||||
REST framework's content negotiation classes handle selection of both the approprate parser for the requesr, and the appropriate renderer for the response, so you should implement both the `.select_parser(request, parsers)` and `.select_renderer(request, renderers, format_suffix)` methods.
|
||||
REST framework's content negotiation classes handle selection of both the appropriate parser for the request, and the appropriate renderer for the response, so you should implement both the `.select_parser(request, parsers)` and `.select_renderer(request, renderers, format_suffix)` methods.
|
||||
|
||||
## Example
|
||||
|
||||
|
@ -63,4 +63,4 @@ request when selecting the appropriate parser or renderer.
|
|||
"""
|
||||
return renderers[0]
|
||||
|
||||
[accept-header]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
|
||||
[accept-header]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
|
||||
|
|
|
@ -25,7 +25,7 @@ For example, the following request:
|
|||
DELETE http://api.example.com/foo/bar HTTP/1.1
|
||||
Accept: application/json
|
||||
|
||||
Might recieve an error response indicating that the `DELETE` method is not allowed on that resource:
|
||||
Might receive an error response indicating that the `DELETE` method is not allowed on that resource:
|
||||
|
||||
HTTP/1.1 405 Method Not Allowed
|
||||
Content-Type: application/json; charset=utf-8
|
||||
|
@ -85,4 +85,4 @@ Raised when an incoming request fails the throttling checks.
|
|||
|
||||
By default this exception results in a response with the HTTP status code "429 Too Many Requests".
|
||||
|
||||
[cite]: http://www.doughellmann.com/articles/how-tos/python-exception-handling/index.html
|
||||
[cite]: http://www.doughellmann.com/articles/how-tos/python-exception-handling/index.html
|
||||
|
|
|
@ -42,7 +42,7 @@ A serializer definition that looked like this:
|
|||
class Meta:
|
||||
fields = ('url', 'owner', 'name', 'expired')
|
||||
|
||||
Would produced output similar to:
|
||||
Would produce output similar to:
|
||||
|
||||
{
|
||||
'url': 'http://example.com/api/accounts/3/',
|
||||
|
@ -51,7 +51,7 @@ Would produced output similar to:
|
|||
'expired': True
|
||||
}
|
||||
|
||||
Be default, the `Field` class will perform a basic translation of the source value into primative datatypes, falling back to unicode representations of complex datatypes when neccesary.
|
||||
By default, the `Field` class will perform a basic translation of the source value into primative datatypes, falling back to unicode representations of complex datatypes when necessary.
|
||||
|
||||
You can customize this behaviour by overriding the `.to_native(self, value)` method.
|
||||
|
||||
|
@ -84,7 +84,7 @@ or `django.db.models.fields.TextField`.
|
|||
|
||||
## EmailField
|
||||
|
||||
A text representation, validates the text to be a valid e-mail adress. Corresponds to `django.db.models.fields.EmailField`
|
||||
A text representation, validates the text to be a valid e-mail address. Corresponds to `django.db.models.fields.EmailField`
|
||||
|
||||
## DateField
|
||||
|
||||
|
@ -165,7 +165,7 @@ And a model serializer defined like this:
|
|||
model = Bookmark
|
||||
exclude = ('id',)
|
||||
|
||||
The an example output format for a Bookmark instance would be:
|
||||
Then an example output format for a Bookmark instance would be:
|
||||
|
||||
{
|
||||
'tags': [u'django', u'python'],
|
||||
|
|
|
@ -8,7 +8,7 @@ sending more complex data than simple forms
|
|||
>
|
||||
> — Malcom Tredinnick, [Django developers group][cite]
|
||||
|
||||
REST framework includes a number of built in Parser classes, that allow you to accept requests with various media types. There is also support for defining your own custom parsers, which gives you the flexiblity to design the media types that your API accepts.
|
||||
REST framework includes a number of built in Parser classes, that allow you to accept requests with various media types. There is also support for defining your own custom parsers, which gives you the flexibility to design the media types that your API accepts.
|
||||
|
||||
## How the parser is determined
|
||||
|
||||
|
@ -65,7 +65,7 @@ Parses `YAML` request content.
|
|||
|
||||
Parses REST framework's default style of `XML` request content.
|
||||
|
||||
Note that the `XML` markup language is used typically used as the base language for more strictly defined domain-specific languages, such as `RSS`, `Atom`, and `XHTML`.
|
||||
Note that the `XML` markup language is typically used as the base language for more strictly defined domain-specific languages, such as `RSS`, `Atom`, and `XHTML`.
|
||||
|
||||
If you are considering using `XML` for your API, you may want to consider implementing a custom renderer and parser for your specific requirements, and using an existing domain-specific media-type, or creating your own custom XML-based media-type.
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@
|
|||
>
|
||||
> — [Apple Developer Documentation][cite]
|
||||
|
||||
Together with [authentication] and [throttling], permissions determine wheter a request should be granted or denied access.
|
||||
Together with [authentication] and [throttling], permissions determine whether a request should be granted or denied access.
|
||||
|
||||
Permission checks are always run at the very start of the view, before any other code is allowed to proceed. Permission checks will typically use the authentication information in the `request.user` and `request.auth` properties to determine if the incoming request should be permitted.
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@
|
|||
>
|
||||
> — [Django documentation][cite]
|
||||
|
||||
REST framework includes a number of built in Renderer classes, that allow you to return responses with various media types. There is also support for defining your own custom renderers, which gives you the flexiblity to design your own media types.
|
||||
REST framework includes a number of built in Renderer classes, that allow you to return responses with various media types. There is also support for defining your own custom renderers, which gives you the flexibility to design your own media types.
|
||||
|
||||
## How the renderer is determined
|
||||
|
||||
|
@ -229,7 +229,7 @@ For example:
|
|||
|
||||
## Designing your media types
|
||||
|
||||
For the purposes of many Web APIs, simple `JSON` responses with hyperlinked relations may be sufficient. If you want to fully embrace RESTful design and [HATEOAS] you'll neeed to consider the design and usage of your media types in more detail.
|
||||
For the purposes of many Web APIs, simple `JSON` responses with hyperlinked relations may be sufficient. If you want to fully embrace RESTful design and [HATEOAS] you'll need to consider the design and usage of your media types in more detail.
|
||||
|
||||
In [the words of Roy Fielding][quote], "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.".
|
||||
|
||||
|
|
|
@ -25,19 +25,19 @@ For more details see the [parsers documentation].
|
|||
|
||||
## .FILES
|
||||
|
||||
`request.FILES` returns any uploaded files that may be present in the content of the request body. This is the same as the standard `HttpRequest` behavior, except that the same flexible request parsing that is used for `request.DATA`.
|
||||
`request.FILES` returns any uploaded files that may be present in the content of the request body. This is the same as the standard `HttpRequest` behavior, except that the same flexible request parsing is used for `request.DATA`.
|
||||
|
||||
For more details see the [parsers documentation].
|
||||
|
||||
## .QUERY_PARAMS
|
||||
|
||||
`request.QUERY_PARAMS` is a more correcly named synonym for `request.GET`.
|
||||
`request.QUERY_PARAMS` is a more correctly named synonym for `request.GET`.
|
||||
|
||||
For clarity inside your code, we recommend using `request.QUERY_PARAMS` instead of the usual `request.GET`, as *any* HTTP method type may include query parameters.
|
||||
|
||||
## .parsers
|
||||
|
||||
The `APIView` class or `@api_view` decorator will ensure that this property is automatically to a list of `Parser` instances, based on the `parser_classes` set on the view or based on the `DEFAULT_PARSER_CLASSES` setting.
|
||||
The `APIView` class or `@api_view` decorator will ensure that this property is automatically set to a list of `Parser` instances, based on the `parser_classes` set on the view or based on the `DEFAULT_PARSER_CLASSES` setting.
|
||||
|
||||
You won't typically need to access this property.
|
||||
|
||||
|
@ -51,7 +51,7 @@ If a client sends a request with a content-type that cannot be parsed then a `Un
|
|||
|
||||
# Authentication
|
||||
|
||||
REST framework provides flexbile, per-request authentication, that gives you the abilty to:
|
||||
REST framework provides flexible, per-request authentication, that gives you the ability to:
|
||||
|
||||
* Use different authentication policies for different parts of your API.
|
||||
* Support the use of multiple authentication policies.
|
||||
|
@ -75,7 +75,7 @@ For more details see the [authentication documentation].
|
|||
|
||||
## .authenticators
|
||||
|
||||
The `APIView` class or `@api_view` decorator will ensure that this property is automatically to a list of `Authentication` instances, based on the `authentication_classes` set on the view or based on the `DEFAULT_AUTHENTICATORS` setting.
|
||||
The `APIView` class or `@api_view` decorator will ensure that this property is automatically set to a list of `Authentication` instances, based on the `authentication_classes` set on the view or based on the `DEFAULT_AUTHENTICATORS` setting.
|
||||
|
||||
You won't typically need to access this property.
|
||||
|
||||
|
@ -83,7 +83,7 @@ You won't typically need to access this property.
|
|||
|
||||
# Browser enhancements
|
||||
|
||||
REST framework supports a few browser enhancments such as browser-based `PUT` and `DELETE` forms.
|
||||
REST framework supports a few browser enhancements such as browser-based `PUT` and `DELETE` forms.
|
||||
|
||||
## .method
|
||||
|
||||
|
|
|
@ -86,7 +86,7 @@ The `Response` class extends `SimpleTemplateResponse`, and all the usual attribu
|
|||
|
||||
**Signature:** `.render()`
|
||||
|
||||
As with any other `TemplateResponse`, this methd is called to render the serialized data of the response into the final response content. When `.render()` is called, the response content will be set to the result of calling the `.render(data, accepted_media_type, renderer_context)` method on the `accepted_renderer` instance.
|
||||
As with any other `TemplateResponse`, this method is called to render the serialized data of the response into the final response content. When `.render()` is called, the response content will be set to the result of calling the `.render(data, accepted_media_type, renderer_context)` method on the `accepted_renderer` instance.
|
||||
|
||||
You won't typically need to call `.render()` yourself, as it's handled by Django's standard response cycle.
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@
|
|||
>
|
||||
> — Roy Fielding, [Architectural Styles and the Design of Network-based Software Architectures][cite]
|
||||
|
||||
As a rule, it's probably better practice to return absolute URIs from you Web APIs, such as `http://example.com/foobar`, rather than returning relative URIs, such as `/foobar`.
|
||||
As a rule, it's probably better practice to return absolute URIs from your Web APIs, such as `http://example.com/foobar`, rather than returning relative URIs, such as `/foobar`.
|
||||
|
||||
The advantages of doing so are:
|
||||
|
||||
|
|
|
@ -175,7 +175,7 @@ You can add extra fields to a `ModelSerializer` or override the default fields b
|
|||
class Meta:
|
||||
model = Account
|
||||
|
||||
Extra fields can corrospond to any property or callable on the model.
|
||||
Extra fields can correspond to any property or callable on the model.
|
||||
|
||||
## Relational fields
|
||||
|
||||
|
@ -187,7 +187,7 @@ The `PrimaryKeyRelatedField` and `HyperlinkedRelatedField` fields provide altern
|
|||
|
||||
The `ModelSerializer` class can itself be used as a field, in order to serialize relationships using nested representations.
|
||||
|
||||
The `RelatedField` class may be subclassed to create a custom represenation of a relationship. The subclass should override `.to_native()`, and optionally `.from_native()` if deserialization is supported.
|
||||
The `RelatedField` class may be subclassed to create a custom representation of a relationship. The subclass should override `.to_native()`, and optionally `.from_native()` if deserialization is supported.
|
||||
|
||||
All the relational fields may be used for any relationship or reverse relationship on a model.
|
||||
|
||||
|
|
|
@ -80,7 +80,7 @@ The allowed request rate is determined from one of the following (in order of pr
|
|||
|
||||
## UserRateThrottle
|
||||
|
||||
The `UserThrottle` will throttle users to a given rate of requests across the API. The user id is used to generate a unique key to throttle against. Unauthenticted requests will fall back to using the IP address of the incoming request to generate a unique key to throttle against.
|
||||
The `UserThrottle` will throttle users to a given rate of requests across the API. The user id is used to generate a unique key to throttle against. Unauthenticated requests will fall back to using the IP address of the incoming request to generate a unique key to throttle against.
|
||||
|
||||
The allowed request rate is determined from one of the following (in order of preference).
|
||||
|
||||
|
@ -114,7 +114,7 @@ For example, multiple user throttle rates could be implemented by using the foll
|
|||
|
||||
## ScopedRateThrottle
|
||||
|
||||
The `ScopedThrottle` class can be used to restrict access to specific parts of the API. This throttle will only be applied if the view that is being accessed includes a `.throttle_scope` property. The unique throttle key will then be formed by concatenating the "scope" of the request with the unqiue user id or IP address.
|
||||
The `ScopedThrottle` class can be used to restrict access to specific parts of the API. This throttle will only be applied if the view that is being accessed includes a `.throttle_scope` property. The unique throttle key will then be formed by concatenating the "scope" of the request with the unique user id or IP address.
|
||||
|
||||
The allowed request rate is determined by the `DEFAULT_THROTTLE_RATES` setting using a key from the request "scope".
|
||||
|
||||
|
@ -152,6 +152,6 @@ User requests to either `ContactListView` or `ContactDetailView` would be restri
|
|||
|
||||
To create a custom throttle, override `BaseThrottle` and implement `.allow_request(request, view)`. The method should return `True` if the request should be allowed, and `False` otherwise.
|
||||
|
||||
Optionally you may also override the `.wait()` method. If implemented, `.wait()` should return a recomended number of seconds to wait before attempting the next request, or `None`. The `.wait()` method will only be called if `.allow_request()` has previously returned `False`.
|
||||
Optionally you may also override the `.wait()` method. If implemented, `.wait()` should return a recommended number of seconds to wait before attempting the next request, or `None`. The `.wait()` method will only be called if `.allow_request()` has previously returned `False`.
|
||||
|
||||
[permissions]: permissions.md
|
||||
|
|
|
@ -47,7 +47,7 @@ Add `rest_framework` to your `INSTALLED_APPS`.
|
|||
'rest_framework',
|
||||
)
|
||||
|
||||
If you're intending to use the browserable API you'll want to add REST framework's login and logout views. Add the following to your root `urls.py` file.
|
||||
If you're intending to use the browseable API you'll want to add REST framework's login and logout views. Add the following to your root `urls.py` file.
|
||||
|
||||
urlpatterns = patterns('',
|
||||
...
|
||||
|
@ -195,4 +195,4 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|||
|
||||
[group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework
|
||||
[DabApps]: http://dabapps.com
|
||||
[email]: mailto:tom@tomchristie.com
|
||||
[email]: mailto:tom@tomchristie.com
|
||||
|
|
|
@ -5,8 +5,8 @@
|
|||
> — [Jeff Atwood][cite]
|
||||
|
||||
* Explain need to add CSRF token to AJAX requests.
|
||||
* Explain defered CSRF style used by REST framework
|
||||
* Explain deferred CSRF style used by REST framework
|
||||
* Why you should use Django's standard login/logout views, and not REST framework view
|
||||
|
||||
|
||||
[cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html
|
||||
[cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
>
|
||||
> — Mike Amundsen, [REST fest 2012 keynote][cite].
|
||||
|
||||
First off, the disclaimer. The name "Django REST framework" was choosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs".
|
||||
First off, the disclaimer. The name "Django REST framework" was chosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs".
|
||||
|
||||
If you are serious about designing a Hypermedia APIs, you should look to resources outside of this documentation to help inform your design choices.
|
||||
|
||||
|
@ -22,7 +22,7 @@ For a more thorough background, check out Klabnik's [Hypermedia API reading list
|
|||
|
||||
## Building Hypermedia APIs with REST framework
|
||||
|
||||
REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style.
|
||||
REST framework is an agnostic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style.
|
||||
|
||||
## What REST framework provides.
|
||||
|
||||
|
@ -50,4 +50,4 @@ What REST framework doesn't do is give you is machine readable hypermedia format
|
|||
[parser]: ../api-guide/parsers.md
|
||||
[renderer]: ../api-guide/renderers.md
|
||||
[fields]: ../api-guide/fields.md
|
||||
[conneg]: ../api-guide/content-negotiation.md
|
||||
[conneg]: ../api-guide/content-negotiation.md
|
||||
|
|
|
@ -5,7 +5,7 @@ Let's introduce a couple of essential building blocks.
|
|||
|
||||
## Request objects
|
||||
|
||||
REST framework intoduces a `Request` object that extends the regular `HttpRequest`, and provides more flexible request parsing. The core functionality of the `Request` object is the `request.DATA` attribute, which is similar to `request.POST`, but more useful for working with Web APIs.
|
||||
REST framework introduces a `Request` object that extends the regular `HttpRequest`, and provides more flexible request parsing. The core functionality of the `Request` object is the `request.DATA` attribute, which is similar to `request.POST`, but more useful for working with Web APIs.
|
||||
|
||||
request.POST # Only handles form data. Only works for 'POST' method.
|
||||
request.DATA # Handles arbitrary data. Works any HTTP request with content.
|
||||
|
|
|
@ -107,7 +107,7 @@ Let's take a look at how we can compose our views by using the mixin classes.
|
|||
|
||||
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`.
|
||||
|
||||
The base class provides the core functionality, and the mixin classes provide the `.list()` and `.create()` actions. We're then explictly binding the `get` and `post` methods to the appropriate actions. Simple enough stuff so far.
|
||||
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.
|
||||
|
||||
class CommentInstance(mixins.RetrieveModelMixin,
|
||||
mixins.UpdateModelMixin,
|
||||
|
|
|
@ -5,7 +5,7 @@ Resource classes are just View classes that don't have any handler methods bound
|
|||
This allows us to:
|
||||
|
||||
* Encapsulate common behaviour across a class of views, in a single Resource class.
|
||||
* Separate out the actions of a Resource from the specfics of how those actions should be bound to a particular set of URLs.
|
||||
* Separate out the actions of a Resource from the specifics of how those actions should be bound to a particular set of URLs.
|
||||
|
||||
## Refactoring to use Resources, not Views
|
||||
|
||||
|
|
|
@ -60,7 +60,7 @@ class SimpleRateThrottle(BaseThrottle):
|
|||
Determine the string representation of the allowed request rate.
|
||||
"""
|
||||
if not getattr(self, 'scope', None):
|
||||
msg = ("You must set either `.scope` or `.rate` for '%s' thottle" %
|
||||
msg = ("You must set either `.scope` or `.rate` for '%s' throttle" %
|
||||
self.__class__.__name__)
|
||||
raise exceptions.ConfigurationError(msg)
|
||||
|
||||
|
@ -137,7 +137,7 @@ class AnonRateThrottle(SimpleRateThrottle):
|
|||
"""
|
||||
Limits the rate of API calls that may be made by a anonymous users.
|
||||
|
||||
The IP address of the request will be used as the unqiue cache key.
|
||||
The IP address of the request will be used as the unique cache key.
|
||||
"""
|
||||
scope = 'anon'
|
||||
|
||||
|
|
Loading…
Reference in New Issue
Block a user