diff options
Diffstat (limited to 'docs/api-guide/settings.md')
| -rw-r--r-- | docs/api-guide/settings.md | 84 |
1 files changed, 72 insertions, 12 deletions
diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 5aee52aa..9005511b 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -1,4 +1,4 @@ -<a class="github" href="settings.py"></a> +source: settings.py # Settings @@ -51,7 +51,7 @@ Default: #### DEFAULT_PARSER_CLASSES -A list or tuple of parser classes, that determines the default set of parsers used when accessing the `request.DATA` property. +A list or tuple of parser classes, that determines the default set of parsers used when accessing the `request.data` property. Default: @@ -74,7 +74,7 @@ Default: #### DEFAULT_PERMISSION_CLASSES -A list or tuple of permission classes, that determines the default set of permissions checked at the start of a view. +A list or tuple of permission classes, that determines the default set of permissions checked at the start of a view. Permission must be granted by every class in the list. Default: @@ -100,12 +100,6 @@ Default: `'rest_framework.negotiation.DefaultContentNegotiation'` *The following settings control the behavior of the generic class based views.* -#### DEFAULT_MODEL_SERIALIZER_CLASS - -A class that determines the default type of model serializer that should be used by a generic view if `model` is specified, but `serializer_class` is not provided. - -Default: `'rest_framework.serializers.ModelSerializer'` - #### DEFAULT_PAGINATION_SERIALIZER_CLASS A class the determines the default serialization style for paginated responses. @@ -158,6 +152,18 @@ A client request like the following would return a paginated list of up to 100 i Default: `None` +### SEARCH_PARAM + +The name of a query parameter, which can be used to specify the search term used by `SearchFilter`. + +Default: `search` + +#### ORDERING_PARAM + +The name of a query parameter, which can be used to specify the ordering of results returned by `OrderingFilter`. + +Default: `ordering` + --- ## Authentication settings @@ -259,7 +265,7 @@ A format string that should be used by default for rendering the output of `Date May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. -Default: `None` +Default: `'iso-8601'` #### DATETIME_INPUT_FORMATS @@ -275,7 +281,7 @@ A format string that should be used by default for rendering the output of `Date May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. -Default: `None` +Default: `'iso-8601'` #### DATE_INPUT_FORMATS @@ -291,7 +297,7 @@ A format string that should be used by default for rendering the output of `Time May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. -Default: `None` +Default: `'iso-8601'` #### TIME_INPUT_FORMATS @@ -303,6 +309,46 @@ Default: `['iso-8601']` --- +## Encodings + +#### UNICODE_JSON + +When set to `True`, JSON responses will allow unicode characters in responses. For example: + + {"unicode black star":"★"} + +When set to `False`, JSON responses will escape non-ascii characters, like so: + + {"unicode black star":"\u2605"} + +Both styles conform to [RFC 4627][rfc4627], and are syntactically valid JSON. The unicode style is preferred as being more user-friendly when inspecting API responses. + +Default: `True` + +#### COMPACT_JSON + +When set to `True`, JSON responses will return compact representations, with no spacing after `':'` and `','` characters. For example: + + {"is_admin":false,"email":"jane@example"} + +When set to `False`, JSON responses will return slightly more verbose representations, like so: + + {"is_admin": false, "email": "jane@example"} + +The default style is to return minified responses, in line with [Heroku's API design guidelines][heroku-minified-json]. + +Default: `True` + +#### COERCE_DECIMAL_TO_STRING + +When returning decimal objects in API representations that do not support a native decimal type, it is normally best to return the value as a string. This avoids the loss of precision that occurs with binary floating point implementations. + +When set to `True`, the serializer `DecimalField` class will return strings instead of `Decimal` objects. When set to `False`, serializers will return `Decimal` objects, which the default JSON encoder will return as floats. + +Default: `True` + +--- + ## View names and descriptions **The following settings are used to generate the view names and descriptions, as used in responses to `OPTIONS` requests, and as used in the browsable API.** @@ -353,6 +399,12 @@ This should be a function with the following signature: Default: `'rest_framework.views.exception_handler'` +#### NON_FIELD_ERRORS_KEY + +A string representing the key that should be used for serializer errors that do not refer to a specific field, but are instead general errors. + +Default: `'non_field_errors'` + #### URL_FIELD_NAME A string representing the key that should be used for the URL fields generated by `HyperlinkedModelSerializer`. @@ -365,5 +417,13 @@ The name of a parameter in the URL conf that may be used to provide a format suf Default: `'format'` +#### NUM_PROXIES + +An integer of 0 or more, that may be used to specify the number of application proxies that the API runs behind. This allows throttling to more accurately identify client IP addresses. If set to `None` then less strict IP matching will be used by the throttle classes. + +Default: `None` + [cite]: http://www.python.org/dev/peps/pep-0020/ +[rfc4627]: http://www.ietf.org/rfc/rfc4627.txt +[heroku-minified-json]: https://github.com/interagent/http-api-design#keep-json-minified-in-all-responses [strftime]: http://docs.python.org/2/library/time.html#time.strftime |