@@ -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,
This can be useful for testing the API from a web browser, where you don't
have any control over what is sent in the `Accept` header.
## URL based accept headers
## URL based format suffixes
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.
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.
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>
