mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-09-21 03:19:00 +03:00
Add docs for OAuth, XML, YAML, JSONP packages. Closes #2179.
This commit is contained in:
Tom Christie
parent
6168f60ba8
commit
17665aa52a
|
|
@ -190,8 +190,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|||
[sandbox]: http://restframework.herokuapp.com/
|
||||
|
||||
[index]: http://www.django-rest-framework.org/
|
||||
[oauth1-section]: http://www.django-rest-framework.org/api-guide/authentication.html#oauthauthentication
|
||||
[oauth2-section]: http://www.django-rest-framework.org/api-guide/authentication.html#oauth2authentication
|
||||
[oauth1-section]: http://www.django-rest-framework.org/api-guide/authentication/#django-rest-framework-oauth
|
||||
[oauth2-section]: http://www.django-rest-framework.org/api-guide/authentication/#django-oauth-toolkit
|
||||
[serializer-section]: http://www.django-rest-framework.org/api-guide/serializers.html#serializers
|
||||
[modelserializer-section]: http://www.django-rest-framework.org/api-guide/serializers.html#modelserializer
|
||||
[functionview-section]: http://www.django-rest-framework.org/api-guide/views.html#function-based-views
|
||||
|
|
|
|||
|
|
@ -293,14 +293,49 @@ The following example will authenticate any incoming request as the user given b
|
|||
|
||||
The following third party packages are also available.
|
||||
|
||||
## Django OAuth Toolkit
|
||||
|
||||
The [Django OAuth Toolkit][django-oauth-toolkit] package provides OAuth 2.0 support, and works with Python 2.7 and Python 3.3+. The package is maintained by [Evonove][evonove] and uses the excellent [OAuthLib][oauthlib]. The package is well documented, and well supported and is currently our **recommended package for OAuth 2.0 support**.
|
||||
|
||||
#### Installation & configuration
|
||||
|
||||
Install using `pip`.
|
||||
|
||||
pip install django-oauth-toolkit
|
||||
|
||||
Add the package to your `INSTALLED_APPS` and modify your REST framework settings.
|
||||
|
||||
INSTALLED_APPS = (
|
||||
...
|
||||
'oauth2_provider',
|
||||
)
|
||||
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_AUTHENTICATION_CLASSES': (
|
||||
'oauth2_provider.ext.rest_framework.OAuth2Authentication',
|
||||
)
|
||||
}
|
||||
|
||||
For more details see the [Django REST framework - Getting started][django-oauth-toolkit-getting-started] documentation.
|
||||
|
||||
## Django REST framework OAuth
|
||||
|
||||
The [Django REST framework OAuth][django-rest-framework-oauth] package provides both OAuth1 and OAuth2 support for REST framework.
|
||||
|
||||
This package was previously included directly in REST framework but is now supported and maintained as a third party package.
|
||||
|
||||
#### Installation & configuration
|
||||
|
||||
Install the package using `pip`.
|
||||
|
||||
pip install djangorestframework-oauth
|
||||
|
||||
For details on configuration and usage see the Django REST framework OAuth documentation for [authentication][django-rest-framework-oauth-authentication] and [permissions][django-rest-framework-oauth-permissions].
|
||||
|
||||
## Digest Authentication
|
||||
|
||||
HTTP digest authentication is a widely implemented scheme that was intended to replace HTTP basic authentication, and which provides a simple encrypted authentication mechanism. [Juan Riaza][juanriaza] maintains the [djangorestframework-digestauth][djangorestframework-digestauth] package which provides HTTP digest authentication support for REST framework.
|
||||
|
||||
## Django OAuth Toolkit
|
||||
|
||||
The [Django OAuth Toolkit][django-oauth-toolkit] package provides OAuth 2.0 support, and works with Python 2.7 and Python 3.3+. The package is maintained by [Evonove][evonove] and uses the excellent [OAuthLib][oauthlib]. The package is well documented, and comes as a recommended alternative for OAuth 2.0 support.
|
||||
|
||||
## Django OAuth2 Consumer
|
||||
|
||||
The [Django OAuth2 Consumer][doac] library from [Rediker Software][rediker] is another package that provides [OAuth 2.0 support for REST framework][doac-rest-framework]. The package includes token scoping permissions on tokens, which allows finer-grained access to your API.
|
||||
|
|
@ -332,6 +367,10 @@ HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a
|
|||
[mod_wsgi_official]: http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization
|
||||
[custom-user-model]: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#specifying-a-custom-user-model
|
||||
[south-dependencies]: http://south.readthedocs.org/en/latest/dependencies.html
|
||||
[django-oauth-toolkit-getting-started]: https://django-oauth-toolkit.readthedocs.org/en/latest/rest-framework/getting_started.html
|
||||
[django-rest-framework-oauth]: http://jpadilla.github.io/django-rest-framework-oauth/
|
||||
[django-rest-framework-oauth-authentication]: http://jpadilla.github.io/django-rest-framework-oauth/authentication/
|
||||
[django-rest-framework-oauth-permissions]: http://jpadilla.github.io/django-rest-framework-oauth/permissions/
|
||||
[juanriaza]: https://github.com/juanriaza
|
||||
[djangorestframework-digestauth]: https://github.com/juanriaza/django-rest-framework-digestauth
|
||||
[oauth-1.0a]: http://oauth.net/core/1.0a
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ As an example, if you are sending `json` encoded data using jQuery with the [.aj
|
|||
|
||||
## Setting the parsers
|
||||
|
||||
The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSES` setting. For example, the following settings would allow requests with `JSON` content.
|
||||
The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSES` setting. For example, the following settings would allow only requests with `JSON` content, instead of the default of JSON or form data.
|
||||
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_PARSER_CLASSES': (
|
||||
|
|
@ -37,8 +37,8 @@ The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSE
|
|||
You can also set the parsers used for an individual view, or viewset,
|
||||
using the `APIView` class based views.
|
||||
|
||||
from rest_framework.parsers import JSONParser
|
||||
from rest_framework.response import Response
|
||||
from rest_framework.parsers import JSONParser
|
||||
from rest_framework.response import Response
|
||||
from rest_framework.views import APIView
|
||||
|
||||
class ExampleView(APIView):
|
||||
|
|
@ -162,6 +162,48 @@ The following is an example plaintext parser that will populate the `request.dat
|
|||
|
||||
The following third party packages are also available.
|
||||
|
||||
## YAML
|
||||
|
||||
[REST framework YAML][rest-framework-yaml] provides [YAML][yaml] parsing and rendering support. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.
|
||||
|
||||
#### Installation & configuration
|
||||
|
||||
Install using pip.
|
||||
|
||||
$ pip install djangorestframework-yaml
|
||||
|
||||
Modify your REST framework settings.
|
||||
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_PARSER_CLASSES': (
|
||||
'rest_framework_yaml.parsers.YAMLParser',
|
||||
),
|
||||
'DEFAULT_RENDERER_CLASSES': (
|
||||
'rest_framework_yaml.renderers.YAMLRenderer',
|
||||
),
|
||||
}
|
||||
|
||||
## XML
|
||||
|
||||
[REST Framework XML][rest-framework-xml] provides a simple informal XML format. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.
|
||||
|
||||
#### Installation & configuration
|
||||
|
||||
Install using pip.
|
||||
|
||||
$ pip install djangorestframework-xml
|
||||
|
||||
Modify your REST framework settings.
|
||||
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_PARSER_CLASSES': (
|
||||
'rest_framework_xml.parsers.XMLParser',
|
||||
),
|
||||
'DEFAULT_RENDERER_CLASSES': (
|
||||
'rest_framework_xml.renderers.XMLRenderer',
|
||||
),
|
||||
}
|
||||
|
||||
## MessagePack
|
||||
|
||||
[MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the [djangorestframework-msgpack][djangorestframework-msgpack] package which provides MessagePack renderer and parser support for REST framework.
|
||||
|
|
@ -173,6 +215,9 @@ The following third party packages are also available.
|
|||
[jquery-ajax]: http://api.jquery.com/jQuery.ajax/
|
||||
[cite]: https://groups.google.com/d/topic/django-developers/dxI4qVzrBY4/discussion
|
||||
[upload-handlers]: https://docs.djangoproject.com/en/dev/topics/http/file-uploads/#upload-handlers
|
||||
[rest-framework-yaml]: http://jpadilla.github.io/django-rest-framework-yaml/
|
||||
[rest-framework-xml]: http://jpadilla.github.io/django-rest-framework-xml/
|
||||
[yaml]: http://www.yaml.org/
|
||||
[messagepack]: https://github.com/juanriaza/django-rest-framework-msgpack
|
||||
[juanriaza]: https://github.com/juanriaza
|
||||
[vbabiy]: https://github.com/vbabiy
|
||||
|
|
|
|||
|
|
@ -342,13 +342,81 @@ Templates will render with a `RequestContext` which includes the `status_code` a
|
|||
|
||||
The following third party packages are also available.
|
||||
|
||||
## YAML
|
||||
|
||||
[REST framework YAML][rest-framework-yaml] provides [YAML][yaml] parsing and rendering support. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.
|
||||
|
||||
#### Installation & configuration
|
||||
|
||||
Install using pip.
|
||||
|
||||
$ pip install djangorestframework-yaml
|
||||
|
||||
Modify your REST framework settings.
|
||||
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_PARSER_CLASSES': (
|
||||
'rest_framework_yaml.parsers.YAMLParser',
|
||||
),
|
||||
'DEFAULT_RENDERER_CLASSES': (
|
||||
'rest_framework_yaml.renderers.YAMLRenderer',
|
||||
),
|
||||
}
|
||||
|
||||
## XML
|
||||
|
||||
[REST Framework XML][rest-framework-xml] provides a simple informal XML format. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.
|
||||
|
||||
#### Installation & configuration
|
||||
|
||||
Install using pip.
|
||||
|
||||
$ pip install djangorestframework-xml
|
||||
|
||||
Modify your REST framework settings.
|
||||
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_PARSER_CLASSES': (
|
||||
'rest_framework_xml.parsers.XMLParser',
|
||||
),
|
||||
'DEFAULT_RENDERER_CLASSES': (
|
||||
'rest_framework_xml.renderers.XMLRenderer',
|
||||
),
|
||||
}
|
||||
|
||||
## JSONP
|
||||
|
||||
[REST framework JSONP][rest-framework-jsonp] provides JSONP rendering support. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.
|
||||
|
||||
---
|
||||
|
||||
**Warning**: If you require cross-domain AJAX requests, you should generally be using the more modern approach of [CORS][cors] as an alternative to `JSONP`. See the [CORS documentation][cors-docs] for more details.
|
||||
|
||||
The `jsonp` approach is essentially a browser hack, and is [only appropriate for globally readable API endpoints][jsonp-security], where `GET` requests are unauthenticated and do not require any user permissions.
|
||||
|
||||
---
|
||||
|
||||
#### Installation & configuration
|
||||
|
||||
Install using pip.
|
||||
|
||||
$ pip install djangorestframework-jsonp
|
||||
|
||||
Modify your REST framework settings.
|
||||
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_RENDERER_CLASSES': (
|
||||
'rest_framework_yaml.renderers.JSONPRenderer',
|
||||
),
|
||||
}
|
||||
|
||||
## MessagePack
|
||||
|
||||
[MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the [djangorestframework-msgpack][djangorestframework-msgpack] package which provides MessagePack renderer and parser support for REST framework.
|
||||
|
||||
## CSV
|
||||
|
||||
Comma-separated values are a plain-text tabular data format, that can be easily imported into spreadsheet applications. [Mjumbe Poe][mjumbewu] maintains the [djangorestframework-csv][djangorestframework-csv] package which provides CSV renderer support for REST framework.
|
||||
Comma-separated values are a plain-text tabular data format, that can be easily imported into spreadsheet applications. [Mjumbe Poe][mjumbewu] maintains the [djangorestframework-csv][djangorestframework-csv] package which provides CSV renderer support for REST framework.
|
||||
|
||||
## UltraJSON
|
||||
|
||||
|
|
@ -358,7 +426,6 @@ Comma-separated values are a plain-text tabular data format, that can be easily
|
|||
|
||||
[djangorestframework-camel-case] provides camel case JSON renderers and parsers for REST framework. This allows serializers to use Python-style underscored field names, but be exposed in the API as Javascript-style camel case field names. It is maintained by [Vitaly Babiy][vbabiy].
|
||||
|
||||
|
||||
## Pandas (CSV, Excel, PNG)
|
||||
|
||||
[Django REST Pandas] provides a serializer and renderers that support additional data processing and output via the [Pandas] DataFrame API. Django REST Pandas includes renderers for Pandas-style CSV files, Excel workbooks (both `.xls` and `.xlsx`), and a number of [other formats]. It is maintained by [S. Andrew Sheppard][sheppard] as part of the [wq Project][wq].
|
||||
|
|
@ -373,10 +440,19 @@ Comma-separated values are a plain-text tabular data format, that can be easily
|
|||
[application/vnd.github+json]: http://developer.github.com/v3/media/
|
||||
[application/vnd.collection+json]: http://www.amundsen.com/media-types/collection/
|
||||
[django-error-views]: https://docs.djangoproject.com/en/dev/topics/http/views/#customizing-error-views
|
||||
[rest-framework-jsonp]: http://jpadilla.github.io/django-rest-framework-jsonp/
|
||||
[cors]: http://www.w3.org/TR/cors/
|
||||
[cors-docs]: http://www.django-rest-framework.org/topics/ajax-csrf-cors/
|
||||
[jsonp-security]: http://stackoverflow.com/questions/613962/is-jsonp-safe-to-use
|
||||
[rest-framework-yaml]: http://jpadilla.github.io/django-rest-framework-yaml/
|
||||
[rest-framework-xml]: http://jpadilla.github.io/django-rest-framework-xml/
|
||||
[messagepack]: http://msgpack.org/
|
||||
[juanriaza]: https://github.com/juanriaza
|
||||
[mjumbewu]: https://github.com/mjumbewu
|
||||
[vbabiy]: https://github.com/vbabiy
|
||||
[rest-framework-yaml]: http://jpadilla.github.io/django-rest-framework-yaml/
|
||||
[rest-framework-xml]: http://jpadilla.github.io/django-rest-framework-xml/
|
||||
[yaml]: http://www.yaml.org/
|
||||
[djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack
|
||||
[djangorestframework-csv]: https://github.com/mjumbewu/django-rest-framework-csv
|
||||
[ultrajson]: https://github.com/esnme/ultrajson
|
||||
|
|
|
|||
|
|
@ -28,13 +28,12 @@ For more details see the [3.0 release notes][3.0-announcement].
|
|||
<img alt="Django REST Framework" title="Logo by Jake 'Sid' Smith" src="img/logo.png" width="600px" style="display: block; margin: 0 auto 0 auto">
|
||||
</p>
|
||||
|
||||
|
||||
Django REST framework is a powerful and flexible toolkit that makes it easy to build Web APIs.
|
||||
|
||||
Some reasons you might want to use REST framework:
|
||||
|
||||
* The [Web browsable API][sandbox] is a huge usability win for your developers.
|
||||
* [Authentication policies][authentication] including optional packages for [OAuth1a][oauth1-section] and [OAuth2][oauth2-section].
|
||||
* [Authentication policies][authentication] including packages for [OAuth1a][oauth1-section] and [OAuth2][oauth2-section].
|
||||
* [Serialization][serializers] that supports both [ORM][modelserializer-section] and [non-ORM][serializer-section] data sources.
|
||||
* Customizable all the way down - just use [regular function-based views][functionview-section] if you don't need the [more][generic-views] [powerful][viewsets] [features][routers].
|
||||
* [Extensive documentation][index], and [great community support][group].
|
||||
|
|
@ -57,7 +56,6 @@ The following packages are optional:
|
|||
|
||||
* [Markdown][markdown] (2.1.0+) - Markdown support for the browsable API.
|
||||
* [django-filter][django-filter] (0.5.4+) - Filtering support.
|
||||
* [django-restframework-oauth][django-restframework-oauth] package for OAuth 1.0a and 2.0 support.
|
||||
* [django-guardian][django-guardian] (1.1.1+) - Object level permissions support.
|
||||
|
||||
## Installation
|
||||
|
|
@ -260,13 +258,12 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|||
[eventbrite]: https://www.eventbrite.co.uk/about/
|
||||
[markdown]: http://pypi.python.org/pypi/Markdown/
|
||||
[django-filter]: http://pypi.python.org/pypi/django-filter
|
||||
[django-restframework-oauth]: https://github.com/jlafon/django-rest-framework-oauth
|
||||
[django-guardian]: https://github.com/lukaszb/django-guardian
|
||||
[0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X
|
||||
[image]: img/quickstart.png
|
||||
[index]: .
|
||||
[oauth1-section]: api-guide/authentication#oauthauthentication
|
||||
[oauth2-section]: api-guide/authentication#oauth2authentication
|
||||
[oauth1-section]: api-guide/authentication/#django-rest-framework-oauth
|
||||
[oauth2-section]: api-guide/authentication/#django-oauth-toolkit
|
||||
[serializer-section]: api-guide/serializers#serializers
|
||||
[modelserializer-section]: api-guide/serializers#modelserializer
|
||||
[functionview-section]: api-guide/views#function-based-views
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user