@@ -69,6 +69,16 @@ If using the `i18n_patterns` function provided by Django, as well as `format_suf
---
## Query parameter formats
An alternative to the format suffixes is to include the requested format in a query parameter. REST framework provides this option by default, and it is used in the browsable API to switch between differing available representations.
To select a representation using its short format, use the `format` query parameter. For example:`http://example.com/organizations/?format=csv`.
The name of this query parameter can be modified using the `URL_FORMAT_OVERRIDE` setting. Set the value to `None` to disable this behavior.
---
## Accept headers vs. format suffixes
There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that `HTTP Accept` headers should always be used instead.
*Thefollowing settings provide URL or form-based overrides of the default browser behavior.*
#### FORM_METHOD_OVERRIDE
The name of a form field that may be used to override the HTTP method of the form.
If the value of this setting is `None` then form method overloading will be disabled.
Default:`'_method'`
#### FORM_CONTENT_OVERRIDE
The name of a form field that may be used to override the content of the form payload. Must be used together with `FORM_CONTENTTYPE_OVERRIDE`.
If either setting is `None` then form content overloading will be disabled.
Default:`'_content'`
#### FORM_CONTENTTYPE_OVERRIDE
The name of a form field that may be used to override the content type of the form payload. Must be used together with `FORM_CONTENT_OVERRIDE`.
If either setting is `None` then form content overloading will be disabled.
Default:`'_content_type'`
#### URL_FORMAT_OVERRIDE
#### URL_ACCEPT_OVERRIDE
The name of a URL parameter that may be used to override the default content negotiation `Accept` header behavior, by using a `format=…` query parameter in the request URL.
The name of a URL parameter that may be used to override the HTTP `Accept` header.
For example:`http://example.com/organizations/?format=csv`
If the value of this setting is `None` then URL accept overloading will be disabled.
If the value of this setting is `None` then URL format overrides will be disabled.
Default:`'accept'`
Default:`'format'`
#### URL_FORMAT_OVERRIDE
#### FORMAT_SUFFIX_KWARG
The name of a URL parameter that may be used to override the default `Accept` header based content negotiation.
The name of a parameter in the URL conf that may be used to provide a format suffix. This setting is applied when using `format_suffix_patterns` to include suffixed URL patterns.
If the value of this setting is `None` then URL format overloading will be disabled.
For example:`http://example.com/organizations.csv/`
Default:`'format'`
...
...
@@ -451,12 +427,6 @@ A string representing the key that should be used for the URL fields generated b
Default: `'url'`
#### FORMAT_SUFFIX_KWARG
The name of a parameter in the URL conf that may be used to provide a format suffix.
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.
Note that prior to 3.3.0, this support was server-side rather than javascript based. The method overloading style (as used in [Ruby on Rails][rails]) is no longer supported due to subtle issues that it introduces in request parsing.
## HTTP header based method overriding
## Browser based submission of non-form content
REST framework also supports method overriding via the semi-standard `X-HTTP-Method-Override` header. This can be useful if you are working with non-form content such as JSON and are working with an older web server and/or hosting provider that doesn't recognise particular HTTP methods such as `PATCH`. For example [Amazon Web Services ELB][aws_elb].
Browser-based submission of content types such as JSON are supported by the [AJAX form library][ajax-form], using form fields with `data-override='content-type'` and `data-override='content'` attributes.
To use it, make a `POST` request, setting the `X-HTTP-Method-Override` header.
For example:
For example, making a `PATCH` request via `POST` in jQuery:
`request.content_type` would return `"application/json"`, and
`request.stream` would return `"{'count': 1}"`
Prior to version 3.3.0 the semi extension header `X-HTTP-Method-Override` was supported for overriding the request method. This behavior is no longer in core, but can be adding if needed using middleware.
## URL based accept headers
For example:
REST framework can take `?accept=application/json` style URL parameters,
REST framework can take `?format=json` style URL parameters, which can be a
useful shortcut for determining which content type should be returned from
the view.
Until version 3.3.0 REST framework included built-in support for `?accept=application/json` style URL parameters, which would allow the `Accept` header to be overridden.
Since the introduction of the content negotiation API this behavior is no longer included in core, but may be added using a custom content negotiation class, if needed.
For example:
This is a more concise than using the `accept` override, but it also gives
you less control. (For example you can't specify any media type parameters)
<buttonclass="btn btn-primary js-tooltip"name="{{ api_settings.FORM_METHOD_OVERRIDE }}"value="PUT"title="Make a PUT request on the {{ name }} resource">PUT</button>
<buttonclass="btn btn-primary js-tooltip"title="Make a PUT request on the {{ name }} resource">PUT</button>
<buttonclass="btn btn-primary js-tooltip"name="{{ api_settings.FORM_METHOD_OVERRIDE }}"value="PUT"title="Make a PUT request on the {{ name }} resource">PUT</button>
<buttonclass="btn btn-primary js-tooltip"title="Make a PUT request on the {{ name }} resource">PUT</button>
{% endif %}
{% if raw_data_patch_form %}
<buttonclass="btn btn-primary js-tooltip"name="{{ api_settings.FORM_METHOD_OVERRIDE }}"value="PATCH"title="Make a PATCH request on the {{ name }} resource">PATCH</button>
<buttondata-method="PATCH"class="btn btn-primary js-tooltip"title="Make a PATCH request on the {{ name }} resource">PATCH</button>
