mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-11-25 11:04:02 +03:00
minor documentation improvements and fixes (#8903)
* minor documentation improvements and fixes * Update docs/api-guide/fields.md --------- Co-authored-by: Tom Christie <tom@tomchristie.com>
This commit is contained in:
parent
b7523f4b9f
commit
c9e7b68a4c
|
@ -414,7 +414,7 @@ The [HawkREST][hawkrest] library builds on the [Mohawk][mohawk] library to let y
|
||||||
|
|
||||||
## HTTP Signature Authentication
|
## HTTP Signature Authentication
|
||||||
|
|
||||||
HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to [Amazon's HTTP Signature scheme][amazon-http-signature], used by many of its services, it permits stateless, per-request authentication. [Elvio Toccalino][etoccalino] maintains the [djangorestframework-httpsignature][djangorestframework-httpsignature] (outdated) package which provides an easy to use HTTP Signature Authentication mechanism. You can use the updated fork version of [djangorestframework-httpsignature][djangorestframework-httpsignature], which is [drf-httpsig][drf-httpsig].
|
HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to [Amazon's HTTP Signature scheme][amazon-http-signature], used by many of its services, it permits stateless, per-request authentication. [Elvio Toccalino][etoccalino] maintains the [djangorestframework-httpsignature][djangorestframework-httpsignature] (outdated) package which provides an easy-to-use HTTP Signature Authentication mechanism. You can use the updated fork version of [djangorestframework-httpsignature][djangorestframework-httpsignature], which is [drf-httpsig][drf-httpsig].
|
||||||
|
|
||||||
## Djoser
|
## Djoser
|
||||||
|
|
||||||
|
|
|
@ -179,7 +179,7 @@ By default this exception results in a response with the HTTP status code "403 F
|
||||||
|
|
||||||
**Signature:** `NotFound(detail=None, code=None)`
|
**Signature:** `NotFound(detail=None, code=None)`
|
||||||
|
|
||||||
Raised when a resource does not exists at the given URL. This exception is equivalent to the standard `Http404` Django exception.
|
Raised when a resource does not exist at the given URL. This exception is equivalent to the standard `Http404` Django exception.
|
||||||
|
|
||||||
By default this exception results in a response with the HTTP status code "404 Not Found".
|
By default this exception results in a response with the HTTP status code "404 Not Found".
|
||||||
|
|
||||||
|
|
|
@ -251,7 +251,7 @@ Corresponds to `django.forms.fields.IPAddressField` and `django.forms.fields.Gen
|
||||||
|
|
||||||
**Signature**: `IPAddressField(protocol='both', unpack_ipv4=False, **options)`
|
**Signature**: `IPAddressField(protocol='both', unpack_ipv4=False, **options)`
|
||||||
|
|
||||||
* `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case insensitive.
|
* `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case-insensitive.
|
||||||
* `unpack_ipv4` Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.
|
* `unpack_ipv4` Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
@ -294,7 +294,7 @@ Corresponds to `django.db.models.fields.DecimalField`.
|
||||||
* `max_value` Validate that the number provided is no greater than this value.
|
* `max_value` Validate that the number provided is no greater than this value.
|
||||||
* `min_value` Validate that the number provided is no less than this value.
|
* `min_value` Validate that the number provided is no less than this value.
|
||||||
* `localize` Set to `True` to enable localization of input and output based on the current locale. This will also force `coerce_to_string` to `True`. Defaults to `False`. Note that data formatting is enabled if you have set `USE_L10N=True` in your settings file.
|
* `localize` Set to `True` to enable localization of input and output based on the current locale. This will also force `coerce_to_string` to `True`. Defaults to `False`. Note that data formatting is enabled if you have set `USE_L10N=True` in your settings file.
|
||||||
* `rounding` Sets the rounding mode used when quantising to the configured precision. Valid values are [`decimal` module rounding modes][python-decimal-rounding-modes]. Defaults to `None`.
|
* `rounding` Sets the rounding mode used when quantizing to the configured precision. Valid values are [`decimal` module rounding modes][python-decimal-rounding-modes]. Defaults to `None`.
|
||||||
* `normalize_output` Will normalize the decimal value when serialized. This will strip all trailing zeroes and change the value's precision to the minimum required precision to be able to represent the value without loosing data. Defaults to `False`.
|
* `normalize_output` Will normalize the decimal value when serialized. This will strip all trailing zeroes and change the value's precision to the minimum required precision to be able to represent the value without loosing data. Defaults to `False`.
|
||||||
|
|
||||||
#### Example usage
|
#### Example usage
|
||||||
|
@ -321,13 +321,13 @@ Corresponds to `django.db.models.fields.DateTimeField`.
|
||||||
|
|
||||||
* `format` - A string representing the output format. If not specified, this defaults to the same value as the `DATETIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. In this case the datetime encoding will be determined by the renderer.
|
* `format` - A string representing the output format. If not specified, this defaults to the same value as the `DATETIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. In this case the datetime encoding will be determined by the renderer.
|
||||||
* `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `DATETIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`.
|
* `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `DATETIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`.
|
||||||
* `default_timezone` - A `tzinfo` subclass (`zoneinfo` or `pytz`) prepresenting the timezone. If not specified and the `USE_TZ` setting is enabled, this defaults to the [current timezone][django-current-timezone]. If `USE_TZ` is disabled, then datetime objects will be naive.
|
* `default_timezone` - A `tzinfo` subclass (`zoneinfo` or `pytz`) representing the timezone. If not specified and the `USE_TZ` setting is enabled, this defaults to the [current timezone][django-current-timezone]. If `USE_TZ` is disabled, then datetime objects will be naive.
|
||||||
|
|
||||||
#### `DateTimeField` format strings.
|
#### `DateTimeField` format strings.
|
||||||
|
|
||||||
Format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`)
|
Format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`)
|
||||||
|
|
||||||
When a value of `None` is used for the format `datetime` objects will be returned by `to_representation` and the final output representation will determined by the renderer class.
|
When a value of `None` is used for the format `datetime` objects will be returned by `to_representation` and the final output representation will be determined by the renderer class.
|
||||||
|
|
||||||
#### `auto_now` and `auto_now_add` model fields.
|
#### `auto_now` and `auto_now_add` model fields.
|
||||||
|
|
||||||
|
|
|
@ -253,7 +253,7 @@ The `OrderingFilter` class supports simple query parameter controlled ordering o
|
||||||
|
|
||||||
![Ordering Filter](../img/ordering-filter.png)
|
![Ordering Filter](../img/ordering-filter.png)
|
||||||
|
|
||||||
By default, the query parameter is named `'ordering'`, but this may by overridden with the `ORDERING_PARAM` setting.
|
By default, the query parameter is named `'ordering'`, but this may be overridden with the `ORDERING_PARAM` setting.
|
||||||
|
|
||||||
For example, to order users by username:
|
For example, to order users by username:
|
||||||
|
|
||||||
|
@ -269,7 +269,7 @@ Multiple orderings may also be specified:
|
||||||
|
|
||||||
### Specifying which fields may be ordered against
|
### Specifying which fields may be ordered against
|
||||||
|
|
||||||
It's recommended that you explicitly specify which fields the API should allowing in the ordering filter. You can do this by setting an `ordering_fields` attribute on the view, like so:
|
It's recommended that you explicitly specify which fields the API should allow in the ordering filter. You can do this by setting an `ordering_fields` attribute on the view, like so:
|
||||||
|
|
||||||
class UserListView(generics.ListAPIView):
|
class UserListView(generics.ListAPIView):
|
||||||
queryset = User.objects.all()
|
queryset = User.objects.all()
|
||||||
|
|
|
@ -262,7 +262,7 @@ API responses for list endpoints will now include a `Link` header, instead of in
|
||||||
|
|
||||||
![Link Header][link-header]
|
![Link Header][link-header]
|
||||||
|
|
||||||
*A custom pagination style, using the 'Link' header'*
|
*A custom pagination style, using the 'Link' header*
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
@ -11,7 +11,7 @@ sending more complex data than simple forms
|
||||||
>
|
>
|
||||||
> — Malcom Tredinnick, [Django developers group][cite]
|
> — 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 flexibility 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
|
## How the parser is determined
|
||||||
|
|
||||||
|
|
|
@ -758,11 +758,11 @@ This is `True` by default, but can be set to `False` if you want to disallow emp
|
||||||
|
|
||||||
### `max_length`
|
### `max_length`
|
||||||
|
|
||||||
This is `None` by default, but can be set to a positive integer if you want to validates that the list contains no more than this number of elements.
|
This is `None` by default, but can be set to a positive integer if you want to validate that the list contains no more than this number of elements.
|
||||||
|
|
||||||
### `min_length`
|
### `min_length`
|
||||||
|
|
||||||
This is `None` by default, but can be set to a positive integer if you want to validates that the list contains no fewer than this number of elements.
|
This is `None` by default, but can be set to a positive integer if you want to validate that the list contains no fewer than this number of elements.
|
||||||
|
|
||||||
### Customizing `ListSerializer` behavior
|
### Customizing `ListSerializer` behavior
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue
Block a user