` methods
+to your `Serializer` subclass. This is documented in the
+[Serializer docs](http://www.django-rest-framework.org/api-guide/serializers/#field-level-validation)
+
+## Class-based
+
+To write a class-based validator, use the `__call__` method. Class-based validators are useful as they allow you to parameterize and reuse behavior.
class MultipleOf(object):
def __init__(self, base):
@@ -215,11 +293,11 @@ To write a class based validator, use the `__call__` method. Class based validat
#### Using `set_context()`
-In some advanced cases you might want a validator to be passed the serializer field it is being used with as additional context. You can do so by declaring a `set_context` method on a class based validator.
+In some advanced cases you might want a validator to be passed the serializer field it is being used with as additional context. You can do so by declaring a `set_context` method on a class-based validator.
def set_context(self, serializer_field):
# Determine if this is an update or a create operation.
# In `__call__` we can then use that information to modify the validation behavior.
self.is_update = serializer_field.parent.instance is not None
-[cite]: https://docs.djangoproject.com/en/dev/ref/validators/
+[cite]: https://docs.djangoproject.com/en/stable/ref/validators/
diff --git a/docs/api-guide/versioning.md b/docs/api-guide/versioning.md
index 54aa0170d..29672c96e 100644
--- a/docs/api-guide/versioning.md
+++ b/docs/api-guide/versioning.md
@@ -71,8 +71,8 @@ You can also set the versioning scheme on an individual view. Typically you won'
The following settings keys are also used to control versioning:
* `DEFAULT_VERSION`. The value that should be used for `request.version` when no versioning information is present. Defaults to `None`.
-* `ALLOWED_VERSIONS`. If set, this value will restrict the set of versions that may be returned by the versioning scheme, and will raise an error if the provided version if not in this set. Note that the value used for the `DEFAULT_VERSION` setting is always considered to be part of the `ALLOWED_VERSIONS` set. Defaults to `None`.
-* `VERSION_PARAM`. The string that should used for any versioning parameters, such as in the media type or URL query parameters. Defaults to `'version'`.
+* `ALLOWED_VERSIONS`. If set, this value will restrict the set of versions that may be returned by the versioning scheme, and will raise an error if the provided version is not in this set. Note that the value used for the `DEFAULT_VERSION` setting is always considered to be part of the `ALLOWED_VERSIONS` set (unless it is `None`). Defaults to `None`.
+* `VERSION_PARAM`. The string that should be used for any versioning parameters, such as in the media type or URL query parameters. Defaults to `'version'`.
You can also set your versioning class plus those three values on a per-view or a per-viewset basis by defining your own versioning scheme and using the `default_version`, `allowed_versions` and `version_param` class variables. For example, if you want to use `URLPathVersioning`:
diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md
index 291fe7376..c0c4f67e4 100644
--- a/docs/api-guide/views.md
+++ b/docs/api-guide/views.md
@@ -1,9 +1,9 @@
source: decorators.py
views.py
-# Class Based Views
+# Class-based Views
-> Django's class based views are a welcome departure from the old-style views.
+> Django's class-based views are a welcome departure from the old-style views.
>
> — [Reinout van Rees][cite]
@@ -73,6 +73,8 @@ The following methods are used by REST framework to instantiate the various plug
### .get_content_negotiator(self)
+### .get_exception_handler(self)
+
## API policy implementation methods
The following methods are called before dispatching to the handler method.
@@ -119,7 +121,7 @@ You won't typically need to override this method.
# Function Based Views
-> Saying [that Class based views] is always the superior solution is a mistake.
+> Saying [that class-based views] is always the superior solution is a mistake.
>
> — [Nick Coghlan][cite2]
@@ -127,7 +129,7 @@ REST framework also allows you to work with regular function based views. It pr
## @api_view()
-**Signature:** `@api_view(http_method_names=['GET'])`
+**Signature:** `@api_view(http_method_names=['GET'], exclude_from_schema=False)`
The core of this functionality is the `api_view` decorator, which takes a list of HTTP methods that your view should respond to. For example, this is how you would write a very simple view that just manually returns some data:
@@ -139,7 +141,7 @@ The core of this functionality is the `api_view` decorator, which takes a list o
This view will use the default renderers, parsers, authentication classes etc specified in the [settings].
-By default only `GET` methods will be accepted. Other methods will respond with "405 Method Not Allowed". To alter this behavior, specify which methods the view allows, like so:
+By default only `GET` methods will be accepted. Other methods will respond with "405 Method Not Allowed". To alter this behaviour, specify which methods the view allows, like so:
@api_view(['GET', 'POST'])
def hello_world(request):
@@ -147,6 +149,13 @@ By default only `GET` methods will be accepted. Other methods will respond with
return Response({"message": "Got some data!", "data": request.data})
return Response({"message": "Hello, world!"})
+You can also mark an API view as being omitted from any [auto-generated schema][schemas],
+using the `exclude_from_schema` argument.:
+
+ @api_view(['GET'], exclude_from_schema=True)
+ def api_docs(request):
+ ...
+
## API policy decorators
To override the default settings, REST framework provides a set of additional decorators which can be added to your views. These must come *after* (below) the `@api_view` decorator. For example, to create a view that uses a [throttle][throttling] to ensure it can only be called once per day by a particular user, use the `@throttle_classes` decorator, passing a list of throttle classes:
@@ -178,3 +187,4 @@ Each of these decorators takes a single argument which must be a list or tuple o
[cite2]: http://www.boredomandlaziness.org/2012/05/djangos-cbvs-are-not-mistake-but.html
[settings]: settings.md
[throttling]: throttling.md
+[schemas]: schemas.md
diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md
index 0452a0f7b..e6df17f51 100644
--- a/docs/api-guide/viewsets.md
+++ b/docs/api-guide/viewsets.md
@@ -179,7 +179,7 @@ In order to use a `GenericViewSet` class you'll override the class and either mi
The `ModelViewSet` class inherits from `GenericAPIView` and includes implementations for various actions, by mixing in the behavior of the various mixin classes.
-The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, and `.destroy()`.
+The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, `.partial_update()`, and `.destroy()`.
#### Example
diff --git a/docs/img/corejson-format.png b/docs/img/corejson-format.png
new file mode 100644
index 000000000..36c197a0d
Binary files /dev/null and b/docs/img/corejson-format.png differ
diff --git a/docs/img/premium/machinalis-readme.png b/docs/img/premium/machinalis-readme.png
new file mode 100644
index 000000000..cd98c23c7
Binary files /dev/null and b/docs/img/premium/machinalis-readme.png differ
diff --git a/docs/img/premium/rollbar-readme.png b/docs/img/premium/rollbar-readme.png
new file mode 100644
index 000000000..669612f72
Binary files /dev/null and b/docs/img/premium/rollbar-readme.png differ
diff --git a/docs/img/premium/rover-readme.png b/docs/img/premium/rover-readme.png
new file mode 100644
index 000000000..b8055d62e
Binary files /dev/null and b/docs/img/premium/rover-readme.png differ
diff --git a/docs/img/premium/sentry-readme.png b/docs/img/premium/sentry-readme.png
new file mode 100644
index 000000000..5536ce52f
Binary files /dev/null and b/docs/img/premium/sentry-readme.png differ
diff --git a/docs/img/premium/stream-readme.png b/docs/img/premium/stream-readme.png
new file mode 100644
index 000000000..fc3733c70
Binary files /dev/null and b/docs/img/premium/stream-readme.png differ
diff --git a/docs/img/raml.png b/docs/img/raml.png
new file mode 100644
index 000000000..87790dc48
Binary files /dev/null and b/docs/img/raml.png differ
diff --git a/docs/img/rover.png b/docs/img/rover.png
new file mode 100644
index 000000000..93aaca701
Binary files /dev/null and b/docs/img/rover.png differ
diff --git a/docs/index.md b/docs/index.md
index a2635c048..1760ce916 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,3 +1,22 @@
+
+
@@ -38,23 +57,42 @@ Some reasons you might want to use REST framework:
* [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].
-* Used and trusted by large companies such as [Mozilla][mozilla] and [Eventbrite][eventbrite].
+* Used and trusted by internationally recognised companies including [Mozilla][mozilla], [Red Hat][redhat], [Heroku][heroku], and [Eventbrite][eventbrite].
---
-![Screenshot][image]
+## Funding
-**Above**: *Screenshot from the browsable API*
+REST framework is a *collaboratively funded project*. If you use
+REST framework commercially we strongly encourage you to invest in its
+continued development by **[signing up for a paid plan][funding]**.
+
+The initial aim is to provide a single full-time position on REST framework.
+*Every single sign-up makes a significant impact towards making that possible.*
+
+
+
+
+*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Machinalis](https://hello.machinalis.co.uk/), and [Rollbar](https://rollbar.com).*
+
+---
## Requirements
REST framework requires the following:
* Python (2.7, 3.2, 3.3, 3.4, 3.5)
-* Django (1.7+, 1.8, 1.9)
+* Django (1.8, 1.9, 1.10)
The following packages are optional:
+* [coreapi][coreapi] (1.32.0+) - Schema generation support.
* [Markdown][markdown] (2.1.0+) - Markdown support for the browsable API.
* [django-filter][django-filter] (0.9.2+) - Filtering support.
* [django-crispy-forms][django-crispy-forms] - Improved HTML display for filtering.
@@ -147,10 +185,11 @@ The tutorial will walk you through the building blocks that make up REST framewo
* [1 - Serialization][tut-1]
* [2 - Requests & Responses][tut-2]
-* [3 - Class based views][tut-3]
+* [3 - Class-based views][tut-3]
* [4 - Authentication & permissions][tut-4]
* [5 - Relationships & hyperlinked APIs][tut-5]
* [6 - Viewsets & routers][tut-6]
+* [7 - Schemas & client libraries][tut-7]
There is a live example API of the finished tutorial API for testing purposes, [available here][sandbox].
@@ -178,6 +217,7 @@ The API guide is your complete reference manual to all the functionality provide
* [Versioning][versioning]
* [Content negotiation][contentnegotiation]
* [Metadata][metadata]
+* [Schemas][schemas]
* [Format suffixes][formatsuffixes]
* [Returning URLs][reverse]
* [Exceptions][exceptions]
@@ -190,6 +230,7 @@ The API guide is your complete reference manual to all the functionality provide
General guides to using REST framework.
* [Documenting your API][documenting-your-api]
+* [API Clients][api-clients]
* [Internationalization][internationalization]
* [AJAX, CSRF & CORS][ajax-csrf-cors]
* [HTML & Forms][html-and-forms]
@@ -203,7 +244,11 @@ General guides to using REST framework.
* [3.1 Announcement][3.1-announcement]
* [3.2 Announcement][3.2-announcement]
* [3.3 Announcement][3.3-announcement]
+* [3.4 Announcement][3.4-announcement]
+* [3.5 Announcement][3.5-announcement]
* [Kickstarter Announcement][kickstarter-announcement]
+* [Mozilla Grant][mozilla-grant]
+* [Funding][funding]
* [Release Notes][release-notes]
## Development
@@ -216,7 +261,7 @@ Framework.
For support please see the [REST framework discussion group][group], try the `#restframework` channel on `irc.freenode.net`, search [the IRC archives][botbot], or raise a question on [Stack Overflow][stack-overflow], making sure to include the ['django-rest-framework'][django-rest-framework-tag] tag.
-[Paid support is available][paid-support] from [DabApps][dabapps], and can include work on REST framework core, or support with building your REST framework API. Please [contact DabApps][contact-dabapps] if you'd like to discuss commercial support options.
+For priority support please sign up for a [professional or premium sponsorship plan](https://fund.django-rest-framework.org/topics/funding/).
For updates on REST framework development, you may also want to follow [the author][twitter] on Twitter.
@@ -255,7 +300,10 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[mozilla]: http://www.mozilla.org/en-US/about/
+[redhat]: https://www.redhat.com/
+[heroku]: https://www.heroku.com/
[eventbrite]: https://www.eventbrite.co.uk/about/
+[coreapi]: http://pypi.python.org/pypi/coreapi/
[markdown]: http://pypi.python.org/pypi/Markdown/
[django-filter]: http://pypi.python.org/pypi/django-filter
[django-crispy-forms]: https://github.com/maraujop/django-crispy-forms
@@ -269,6 +317,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[modelserializer-section]: api-guide/serializers#modelserializer
[functionview-section]: api-guide/views#function-based-views
[sandbox]: http://restframework.herokuapp.com/
+[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors
[quickstart]: tutorial/quickstart.md
[tut-1]: tutorial/1-serialization.md
@@ -277,6 +326,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[tut-4]: tutorial/4-authentication-and-permissions.md
[tut-5]: tutorial/5-relationships-and-hyperlinked-apis.md
[tut-6]: tutorial/6-viewsets-and-routers.md
+[tut-7]: tutorial/7-schemas-and-client-libraries.md
[request]: api-guide/requests.md
[response]: api-guide/responses.md
@@ -298,6 +348,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[versioning]: api-guide/versioning.md
[contentnegotiation]: api-guide/content-negotiation.md
[metadata]: api-guide/metadata.md
+[schemas]: api-guide/schemas.md
[formatsuffixes]: api-guide/format-suffixes.md
[reverse]: api-guide/reverse.md
[exceptions]: api-guide/exceptions.md
@@ -306,6 +357,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[settings]: api-guide/settings.md
[documenting-your-api]: topics/documenting-your-api.md
+[api-clients]: topics/api-clients.md
[internationalization]: topics/internationalization.md
[ajax-csrf-cors]: topics/ajax-csrf-cors.md
[html-and-forms]: topics/html-and-forms.md
@@ -319,7 +371,10 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[3.1-announcement]: topics/3.1-announcement.md
[3.2-announcement]: topics/3.2-announcement.md
[3.3-announcement]: topics/3.3-announcement.md
+[3.4-announcement]: topics/3.4-announcement.md
+[3.5-announcement]: topics/3.5-announcement.md
[kickstarter-announcement]: topics/kickstarter-announcement.md
+[mozilla-grant]: topics/mozilla-grant.md
[funding]: topics/funding.md
[release-notes]: topics/release-notes.md
diff --git a/docs/topics/2.2-announcement.md b/docs/topics/2.2-announcement.md
index e6220f427..ca4ed2efa 100644
--- a/docs/topics/2.2-announcement.md
+++ b/docs/topics/2.2-announcement.md
@@ -147,10 +147,10 @@ When using a serializer with a `HyperlinkedRelatedField` or `HyperlinkedIdentity
From version 2.2 onwards, serializers with hyperlinked relationships *always* require a `'request'` key to be supplied in the context dictionary. The implicit behavior will continue to function, but its use will raise a `PendingDeprecationWarning`.
[xordoquy]: https://github.com/xordoquy
-[django-python-3]: https://docs.djangoproject.com/en/dev/faq/install/#can-i-use-django-with-python-3
-[porting-python-3]: https://docs.djangoproject.com/en/dev/topics/python3/
-[python-compat]: https://docs.djangoproject.com/en/dev/releases/1.5/#python-compatibility
-[django-deprecation-policy]: https://docs.djangoproject.com/en/dev/internals/release-process/#internal-release-deprecation-policy
+[django-python-3]: https://docs.djangoproject.com/en/stable/faq/install/#can-i-use-django-with-python-3
+[porting-python-3]: https://docs.djangoproject.com/en/stable/topics/python3/
+[python-compat]: https://docs.djangoproject.com/en/stable/releases/1.5/#python-compatibility
+[django-deprecation-policy]: https://docs.djangoproject.com/en/stable/internals/release-process/#internal-release-deprecation-policy
[credits]: http://www.django-rest-framework.org/topics/credits
[mailing-list]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework
[django-rest-framework-docs]: https://github.com/marcgibbons/django-rest-framework-docs
diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md
index 21d9f1dbc..d9bab39dc 100644
--- a/docs/topics/2.3-announcement.md
+++ b/docs/topics/2.3-announcement.md
@@ -6,7 +6,7 @@ REST framework 2.3 makes it even quicker and easier to build your Web APIs.
The 2.3 release introduces the [ViewSet][viewset] and [Router][router] classes.
-A viewset is simply a type of class based view that allows you to group multiple views into a single common class.
+A viewset is simply a type of class-based view that allows you to group multiple views into a single common class.
Routers allow you to automatically determine the URLconf for your viewset classes.
diff --git a/docs/topics/2.4-announcement.md b/docs/topics/2.4-announcement.md
index 4ca35290c..96f68c865 100644
--- a/docs/topics/2.4-announcement.md
+++ b/docs/topics/2.4-announcement.md
@@ -39,7 +39,7 @@ Then run the `runtests.py` script.
./runtests.py
-The new test runner also includes [flake8](https://flake8.readthedocs.org) code linting, which should help keep our coding style consistent.
+The new test runner also includes [flake8](https://flake8.readthedocs.io) code linting, which should help keep our coding style consistent.
#### Test runner flags
@@ -162,7 +162,7 @@ The next planned release will be 3.0, featuring an improved and simplified seria
Once again, many thanks to all the generous [backers and sponsors][kickstarter-sponsors] who've helped make this possible!
-[lts-releases]: https://docs.djangoproject.com/en/dev/internals/release-process/#long-term-support-lts-releases
+[lts-releases]: https://docs.djangoproject.com/en/stable/internals/release-process/#long-term-support-lts-releases
[2-4-release-notes]: release-notes#240
[view-name-and-description-settings]: ../api-guide/settings#view-names-and-descriptions
[client-ip-identification]: ../api-guide/throttling#how-clients-are-identified
diff --git a/docs/topics/3.0-announcement.md b/docs/topics/3.0-announcement.md
index 89f9e8001..f09788f56 100644
--- a/docs/topics/3.0-announcement.md
+++ b/docs/topics/3.0-announcement.md
@@ -426,7 +426,7 @@ There are four methods that can be overridden, depending on what functionality y
* `.to_internal_value()` - Override this to support deserialization, for write operations.
* `.create()` and `.update()` - Override either or both of these to support saving instances.
-Because this class provides the same interface as the `Serializer` class, you can use it with the existing generic class based views exactly as you would for a regular `Serializer` or `ModelSerializer`.
+Because this class provides the same interface as the `Serializer` class, you can use it with the existing generic class-based views exactly as you would for a regular `Serializer` or `ModelSerializer`.
The only difference you'll notice when doing so is the `BaseSerializer` classes will not generate HTML forms in the browsable API. This is because the data they return does not include all the field information that would allow each field to be rendered into a suitable HTML input.
@@ -801,7 +801,7 @@ This change means that you can now easily customize the style of error responses
## The metadata API
-Behavior for dealing with `OPTIONS` requests was previously built directly into the class based views. This has now been properly separated out into a Metadata API that allows the same pluggable style as other API policies in REST framework.
+Behavior for dealing with `OPTIONS` requests was previously built directly into the class-based views. This has now been properly separated out into a Metadata API that allows the same pluggable style as other API policies in REST framework.
This makes it far easier to use a different style for `OPTIONS` responses throughout your API, and makes it possible to create third-party metadata policies.
@@ -870,7 +870,7 @@ The `COMPACT_JSON` setting has been added, and can be used to revert this behavi
#### File fields as URLs
-The `FileField` and `ImageField` classes are now represented as URLs by default. You should ensure you set Django's [standard `MEDIA_URL` setting](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-MEDIA_URL) appropriately, and ensure your application [serves the uploaded files](https://docs.djangoproject.com/en/dev/howto/static-files/#serving-uploaded-files-in-development).
+The `FileField` and `ImageField` classes are now represented as URLs by default. You should ensure you set Django's [standard `MEDIA_URL` setting](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-MEDIA_URL) appropriately, and ensure your application [serves the uploaded files](https://docs.djangoproject.com/en/stable/howto/static-files/#serving-uploaded-files-in-development).
You can revert this behavior, and display filenames in the representation by using the `UPLOADED_FILES_USE_URL` settings key:
@@ -894,11 +894,11 @@ If the request is omitted from the context, the returned URLs will be of the for
The custom `X-Throttle-Wait-Second` header has now been dropped in favor of the standard `Retry-After` header. You can revert this behavior if needed by writing a custom exception handler for your application.
-#### Date and time objects as ISO-8859-1 strings in serializer data.
+#### Date and time objects as ISO-8601 strings in serializer data.
Date and Time objects are now coerced to strings by default in the serializer output. Previously they were returned as `Date`, `Time` and `DateTime` objects, and later coerced to strings by the renderer.
-You can modify this behavior globally by settings the existing `DATE_FORMAT`, `DATETIME_FORMAT` and `TIME_FORMAT` settings keys. Setting these values to `None` instead of their default value of `'iso-8859-1'` will result in native objects being returned in serializer data.
+You can modify this behavior globally by settings the existing `DATE_FORMAT`, `DATETIME_FORMAT` and `TIME_FORMAT` settings keys. Setting these values to `None` instead of their default value of `'iso-8601'` will result in native objects being returned in serializer data.
REST_FRAMEWORK = {
# Return native `Date` and `Time` objects in `serializer.data`
@@ -962,4 +962,4 @@ You can follow development on the GitHub site, where we use [milestones to indic
[kickstarter]: http://kickstarter.com/projects/tomchristie/django-rest-framework-3
[sponsors]: http://www.django-rest-framework.org/topics/kickstarter-announcement/#sponsors
[mixins.py]: https://github.com/tomchristie/django-rest-framework/blob/master/rest_framework/mixins.py
-[django-localization]: https://docs.djangoproject.com/en/dev/topics/i18n/translation/#localization-how-to-create-language-files
+[django-localization]: https://docs.djangoproject.com/en/stable/topics/i18n/translation/#localization-how-to-create-language-files
diff --git a/docs/topics/3.1-announcement.md b/docs/topics/3.1-announcement.md
index 80d4007eb..6cca40665 100644
--- a/docs/topics/3.1-announcement.md
+++ b/docs/topics/3.1-announcement.md
@@ -30,7 +30,7 @@ Note that as a result of this work a number of settings keys and generic view at
Until now, there has only been a single built-in pagination style in REST framework. We now have page, limit/offset and cursor based schemes included by default.
-The cursor based pagination scheme is particularly smart, and is a better approach for clients iterating through large or frequently changing result sets. The scheme supports paging against non-unique indexes, by using both cursor and limit/offset information. It also allows for both forward and reverse cursor pagination. Much credit goes to David Cramer for [this blog post](http://cramer.io/2011/03/08/building-cursors-for-the-disqus-api/) on the subject.
+The cursor based pagination scheme is particularly smart, and is a better approach for clients iterating through large or frequently changing result sets. The scheme supports paging against non-unique indexes, by using both cursor and limit/offset information. It also allows for both forward and reverse cursor pagination. Much credit goes to David Cramer for [this blog post](http://cramer.io/2011/03/08/building-cursors-for-the-disqus-api) on the subject.
#### Pagination controls in the browsable API.
@@ -110,7 +110,7 @@ When per-request internationalization is enabled, client requests will respect t
"detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."
}
-Note that the structure of the error responses is still the same. We still have a `details` key in the response. If needed you can modify this behavior too, by using a [custom exception handler][custom-exception-handler].
+Note that the structure of the error responses is still the same. We still have a `detail` key in the response. If needed you can modify this behavior too, by using a [custom exception handler][custom-exception-handler].
We include built-in translations both for standard exception cases, and for serializer validation errors.
@@ -153,7 +153,7 @@ For more information, see the documentation on [customizing field mappings][cust
We've now moved a number of packages out of the core of REST framework, and into separately installable packages. If you're currently using these you don't need to worry, you simply need to `pip install` the new packages, and change any import paths.
-We're making this change in order to help distribute the maintainance workload, and keep better focus of the core essentials of the framework.
+We're making this change in order to help distribute the maintenance workload, and keep better focus of the core essentials of the framework.
The change also means we can be more flexible with which external packages we recommend. For example, the excellently maintained [Django OAuth toolkit](https://github.com/evonove/django-oauth-toolkit) has now been promoted as our recommended option for integrating OAuth support.
diff --git a/docs/topics/3.2-announcement.md b/docs/topics/3.2-announcement.md
index f0cc09a46..dc439f110 100644
--- a/docs/topics/3.2-announcement.md
+++ b/docs/topics/3.2-announcement.md
@@ -54,7 +54,7 @@ The following pagination view attributes and settings have been moved into attri
* `view.max_paginate_by` - Use `paginator.max_page_size` instead.
* `settings.PAGINATE_BY` - Use `paginator.page_size` instead.
* `settings.PAGINATE_BY_PARAM` - Use `paginator.page_size_query_param` instead.
-* `settings.MAX_PAGINATE_BY` - Use `max_page_size` instead.
+* `settings.MAX_PAGINATE_BY` - Use `paginator.max_page_size` instead.
## Modifications to list behaviors
diff --git a/docs/topics/3.4-announcement.md b/docs/topics/3.4-announcement.md
new file mode 100644
index 000000000..438192c9c
--- /dev/null
+++ b/docs/topics/3.4-announcement.md
@@ -0,0 +1,194 @@
+
+
+# Django REST framework 3.4
+
+The 3.4 release is the first in a planned series that will be addressing schema
+generation, hypermedia support, API clients, and finally realtime support.
+
+---
+
+## Funding
+
+The 3.4 release has been made possible a recent [Mozilla grant][moss], and by our
+[collaborative funding model][funding]. If you use REST framework commercially, and would
+like to see this work continue, we strongly encourage you to invest in its
+continued development by **[signing up for a paid plan][funding]**.
+
+The initial aim is to provide a single full-time position on REST framework.
+Right now we're over 60% of the way towards achieving that.
+*Every single sign-up makes a significant impact.*
+
+
+
+
+*Many thanks to all our [awesome sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), and [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf).*
+
+---
+
+## Schemas & client libraries
+
+REST framework 3.4 brings built-in support for generating API schemas.
+
+We provide this support by using [Core API][core-api], a Document Object Model
+for describing APIs.
+
+Because Core API represents the API schema in an format-independent
+manner, we're able to render the Core API `Document` object into many different
+schema formats, by allowing the renderer class to determine how the internal
+representation maps onto the external schema format.
+
+This approach should also open the door to a range of auto-generated API
+documentation options in the future, by rendering the `Document` object into
+HTML documentation pages.
+
+Alongside the built-in schema support, we're also now providing the following:
+
+* A [command line tool][command-line-client] for interacting with APIs.
+* A [Python client library][client-library] for interacting with APIs.
+
+These API clients are dynamically driven, and able to interact with any API
+that exposes a supported schema format.
+
+Dynamically driven clients allow you to interact with an API at an application
+layer interface, rather than a network layer interface, while still providing
+the benefits of RESTful Web API design.
+
+We're expecting to expand the range of languages that we provide client libraries
+for over the coming months.
+
+Further work on maturing the API schema support is also planned, including
+documentation on supporting file upload and download, and improved support for
+documentation generation and parameter annotation.
+
+---
+
+Current support for schema formats is as follows:
+
+Name | Support | PyPI package
+---------------------------------|-------------------------------------|--------------------------------
+[Core JSON][core-json] | Schema generation & client support. | Built-in support in `coreapi`.
+[Swagger / OpenAPI][swagger] | Schema generation & client support. | The `openapi-codec` package.
+[JSON Hyper-Schema][hyperschema] | Currently client support only. | The `hyperschema-codec` package.
+[API Blueprint][api-blueprint] | Not yet available. | Not yet available.
+
+---
+
+You can read more about any of this new functionality in the following:
+
+* New tutorial section on [schemas & client libraries][tut-7].
+* Documentation page on [schema generation][schema-generation].
+* Topic page on [API clients][api-clients].
+
+It is also worth noting that Marc Gibbons is currently working towards a 2.0 release of
+the popular Django REST Swagger package, which will tie in with our new built-in support.
+
+---
+
+## Supported versions
+
+The 3.4.0 release adds support for Django 1.10.
+
+The following versions of Python and Django are now supported:
+
+* Django versions 1.8, 1.9, and 1.10.
+* Python versions 2.7, 3.2(\*), 3.3(\*), 3.4, 3.5.
+
+(\*) Note that Python 3.2 and 3.3 are not supported from Django 1.9 onwards.
+
+---
+
+## Deprecations and changes
+
+The 3.4 release includes very limited deprecation or behavioral changes, and
+should present a straightforward upgrade.
+
+### Use fields or exclude on serializer classes.
+
+The following change in 3.3.0 is now escalated from "pending deprecation" to
+"deprecated". Its usage will continue to function but will raise warnings:
+
+`ModelSerializer` and `HyperlinkedModelSerializer` should include either a `fields`
+option, or an `exclude` option. The `fields = '__all__'` shortcut may be used
+to explicitly include all fields.
+
+### Microsecond precision when returning time or datetime.
+
+Using the default JSON renderer and directly returning a `datetime` or `time`
+instance will now render with microsecond precision (6 digits), rather than
+millisecond precision (3 digits). This makes the output format consistent with the
+default string output of `serializers.DateTimeField` and `serializers.TimeField`.
+
+This change *does not affect the default behavior when using serializers*,
+which is to serialize `datetime` and `time` instances into strings with
+microsecond precision.
+
+The serializer behavior can be modified if needed, using the `DATETIME_FORMAT`
+and `TIME_FORMAT` settings.
+
+The renderer behavior can be modified by setting a custom `encoder_class`
+attribute on a `JSONRenderer` subclass.
+
+### Relational choices no longer displayed in OPTIONS requests.
+
+Making an `OPTIONS` request to views that have a serializer choice field
+will result in a list of the available choices being returned in the response.
+
+In cases where there is a relational field, the previous behavior would be
+to return a list of available instances to choose from for that relational field.
+
+In order to minimise exposed information the behavior now is to *not* return
+choices information for relational fields.
+
+If you want to override this new behavior you'll need to [implement a custom
+metadata class][metadata].
+
+See [issue #3751][gh3751] for more information on this behavioral change.
+
+---
+
+## Other improvements
+
+This release includes further work from a huge number of [pull requests and issues][milestone].
+
+Many thanks to all our contributors who've been involved in the release, either through raising issues, giving feedback, improving the documentation, or suggesting and implementing code changes.
+
+The full set of itemized release notes [are available here][release-notes].
+
+[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors
+[moss]: mozilla-grant.md
+[funding]: funding.md
+[core-api]: http://www.coreapi.org/
+[command-line-client]: api-clients#command-line-client
+[client-library]: api-clients#python-client-library
+[core-json]: http://www.coreapi.org/specification/encoding/#core-json-encoding
+[swagger]: https://openapis.org/specification
+[hyperschema]: http://json-schema.org/latest/json-schema-hypermedia.html
+[api-blueprint]: https://apiblueprint.org/
+[tut-7]: ../../tutorial/7-schemas-and-client-libraries/
+[schema-generation]: ../../api-guide/schemas/
+[api-clients]: api-clients.md
+[milestone]: https://github.com/tomchristie/django-rest-framework/milestone/35
+[release-notes]: release-notes#34
+[metadata]: ../../api-guide/metadata/#custom-metadata-classes
+[gh3751]: https://github.com/tomchristie/django-rest-framework/issues/3751
diff --git a/docs/topics/3.5-announcement.md b/docs/topics/3.5-announcement.md
new file mode 100644
index 000000000..ea50b2418
--- /dev/null
+++ b/docs/topics/3.5-announcement.md
@@ -0,0 +1,266 @@
+
+
+# Django REST framework 3.5
+
+The 3.5 release is the second in a planned series that is addressing schema
+generation, hypermedia support, API client libraries, and finally realtime support.
+
+---
+
+## Funding
+
+The 3.5 release would not have been possible without our [collaborative funding model][funding].
+If you use REST framework commercially and would like to see this work continue,
+we strongly encourage you to invest in its continued development by
+**[signing up for a paid plan][funding]**.
+
+
+
+
+*Many thanks to all our [sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), and [Machinalis](http://www.machinalis.com/#services).*
+
+---
+
+## Improved schema generation
+
+Docstrings on views are now pulled through into schema definitions, allowing
+you to [use the schema definition to document your API][schema-docs].
+
+There is now also a shortcut function, `get_schema_view()`, which makes it easier to
+[adding schema views][schema-view] to your API.
+
+For example, to include a swagger schema to your API, you would do the following:
+
+* Run `pip install django-rest-swagger`.
+
+* Add `'rest_framework_swagger'` to your `INSTALLED_APPS` setting.
+
+* Include the schema view in your URL conf:
+
+```py
+from rest_framework.schemas import get_schema_view
+from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer
+
+schema_view = get_schema_view(
+ title='Example API',
+ renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer]
+)
+
+urlpatterns = [
+ url(r'^swagger/$', schema_view),
+ ...
+]
+```
+
+There have been a large number of fixes to the schema generation. These should
+resolve issues for anyone using the latest version of the `django-rest-swagger`
+package.
+
+Some of these changes do affect the resulting schema structure,
+so if you're already using schema generation you should make sure to review
+[the deprecation notes](#deprecations), particularly if you're currently using
+a dynamic client library to interact with your API.
+
+Finally, we're also now exposing the schema generation as a
+[publicly documented API][schema-generation-api], allowing you to more easily
+override the behaviour.
+
+## Requests test client
+
+You can now test your project using the `requests` library.
+
+This exposes exactly the same interface as if you were using a standard
+requests session instance.
+
+ client = RequestsClient()
+ response = client.get('http://testserver/users/')
+ assert response.status_code == 200
+
+Rather than sending any HTTP requests to the network, this interface will
+coerce all outgoing requests into WSGI, and call into your application directly.
+
+## Core API client
+
+You can also now test your project by interacting with it using the `coreapi`
+client library.
+
+ # Fetch the API schema
+ client = CoreAPIClient()
+ schema = client.get('http://testserver/schema/')
+
+ # Create a new organisation
+ params = {'name': 'MegaCorp', 'status': 'active'}
+ client.action(schema, ['organisations', 'create'], params)
+
+ # Ensure that the organisation exists in the listing
+ data = client.action(schema, ['organisations', 'list'])
+ assert(len(data) == 1)
+ assert(data == [{'name': 'MegaCorp', 'status': 'active'}])
+
+Again, this will call directly into the application using the WSGI interface,
+rather than making actual network calls.
+
+This is a good option if you are planning for clients to mainly interact with
+your API using the `coreapi` client library, or some other auto-generated client.
+
+## Live tests
+
+One interesting aspect of both the `requests` client and the `coreapi` client
+is that they allow you to write tests in such a way that they can also be made
+to run against a live service.
+
+By switching the WSGI based client instances to actual instances of `requests.Session`
+or `coreapi.Client` you can have the test cases make actual network calls.
+
+Being able to write test cases that can exercise your staging or production
+environment is a powerful tool. However in order to do this, you'll need to pay
+close attention to how you handle setup and teardown to ensure a strict isolation
+of test data from other live or staging data.
+
+## RAML support
+
+We now have preliminary support for [RAML documentation generation][django-rest-raml].
+
+![RAML Example][raml-image]
+
+Further work on the encoding and documentation generation is planned, in order to
+make features such as the 'Try it now' support available at a later date.
+
+This work also now means that you can use the Core API client libraries to interact
+with APIs that expose a RAML specification. The [RAML codec][raml-codec] gives some examples of
+interacting with the Spotify API in this way.
+
+## Validation codes
+
+Exceptions raised by REST framework now include short code identifiers.
+When used together with our customizable error handling, this now allows you to
+modify the style of API error messages.
+
+As an example, this allows for the following style of error responses:
+
+ {
+ "message": "You do not have permission to perform this action.",
+ "code": "permission_denied"
+ }
+
+This is particularly useful with validation errors, which use appropriate
+codes to identify differing kinds of failure...
+
+ {
+ "name": {"message": "This field is required.", "code": "required"},
+ "age": {"message": "A valid integer is required.", "code": "invalid"}
+ }
+
+## Client upload & download support
+
+The Python `coreapi` client library and the Core API command line tool both
+now fully support file [uploads][uploads] and [downloads][downloads].
+
+---
+
+## Deprecations
+
+### Generating schemas from Router
+
+The router arguments for generating a schema view, such as `schema_title`,
+are now pending deprecation.
+
+Instead of using `DefaultRouter(schema_title='Example API')`, you should use
+the `get_schema_view()` function, and include the view in your URL conf.
+
+Make sure to include the view before your router urls. For example:
+
+ from rest_framework.schemas import get_schema_view
+ from my_project.routers import router
+
+ schema_view = get_schema_view(title='Example API')
+
+ urlpatterns = [
+ url('^$', schema_view),
+ url(r'^', include(router.urls)),
+ ]
+
+### Schema path representations
+
+The `'pk'` identifier in schema paths is now mapped onto the actually model field
+name by default. This will typically be `'id'`.
+
+This gives a better external representation for schemas, with less implementation
+detail being exposed. It also reflects the behaviour of using a ModelSerializer
+class with `fields = '__all__'`.
+
+You can revert to the previous behaviour by setting `'SCHEMA_COERCE_PATH_PK': False`
+in the REST framework settings.
+
+### Schema action name representations
+
+The internal `retrieve()` and `destroy()` method names are now coerced to an
+external representation of `read` and `delete`.
+
+You can revert to the previous behaviour by setting `'SCHEMA_COERCE_METHOD_NAMES': {}`
+in the REST framework settings.
+
+### DjangoFilterBackend
+
+The functionality of the built-in `DjangoFilterBackend` is now completely
+included by the `django-filter` package.
+
+You should change your imports and REST framework filter settings as follows:
+
+* `rest_framework.filters.DjangoFilterBackend` becomes `django_filters.rest_framework.DjangoFilterBackend`.
+* `rest_framework.filters.FilterSet` becomes `django_filters.rest_framework.FilterSet`.
+
+The existing imports will continue to work but are now pending deprecation.
+
+### CoreJSON media type
+
+The media type for `CoreJSON` is now `application/json+coreapi`, rather than
+the previous `application/vnd.json+coreapi`. This brings it more into line with
+other custom media types, such as those used by Swagger and RAML.
+
+The clients currently accept either media type. The old style-media type will
+be deprecated at a later date.
+
+### ModelSerializer 'fields' and 'exclude'
+
+ModelSerializer and HyperlinkedModelSerializer must include either a fields
+option, or an exclude option. The `fields = '__all__'` shortcut may be used to
+explicitly include all fields.
+
+Failing to set either `fields` or `exclude` raised a pending deprecation warning
+in version 3.3 and raised a deprecation warning in 3.4. Its usage is now mandatory.
+
+---
+
+[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors
+[funding]: funding.md
+[uploads]: http://core-api.github.io/python-client/api-guide/utils/#file
+[downloads]: http://core-api.github.io/python-client/api-guide/codecs/#downloadcodec
+[schema-generation-api]: ../api-guide/schemas/#schemagenerator
+[schema-docs]: ../api-guide/schemas/#schemas-as-documentation
+[schema-view]: ../api-guide/schemas/#the-get_schema_view-shortcut
+[django-rest-raml]: https://github.com/tomchristie/django-rest-raml
+[raml-image]: ../img/raml.png
+[raml-codec]: https://github.com/core-api/python-raml-codec
diff --git a/docs/topics/ajax-csrf-cors.md b/docs/topics/ajax-csrf-cors.md
index ad88810da..4960e0881 100644
--- a/docs/topics/ajax-csrf-cors.md
+++ b/docs/topics/ajax-csrf-cors.md
@@ -35,7 +35,7 @@ The best way to deal with CORS in REST framework is to add the required response
[cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html
[csrf]: https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)
-[csrf-ajax]: https://docs.djangoproject.com/en/dev/ref/csrf/#ajax
+[csrf-ajax]: https://docs.djangoproject.com/en/stable/ref/csrf/#ajax
[cors]: http://www.w3.org/TR/cors/
[ottoyiu]: https://github.com/ottoyiu/
[django-cors-headers]: https://github.com/ottoyiu/django-cors-headers/
diff --git a/docs/topics/api-clients.md b/docs/topics/api-clients.md
new file mode 100644
index 000000000..fa7b60d3e
--- /dev/null
+++ b/docs/topics/api-clients.md
@@ -0,0 +1,325 @@
+# API Clients
+
+An API client handles the underlying details of how network requests are made
+and how responses are decoded. They present the developer with an application
+interface to work against, rather than working directly with the network interface.
+
+The API clients documented here are not restricted to APIs built with Django REST framework.
+ They can be used with any API that exposes a supported schema format.
+
+For example, [the Heroku platform API][heroku-api] exposes a schema in the JSON
+Hyperschema format. As a result, the Core API command line client and Python
+client library can be [used to interact with the Heroku API][heroku-example].
+
+## Client-side Core API
+
+[Core API][core-api] is a document specification that can be used to describe APIs. It can
+be used either server-side, as is done with REST framework's [schema generation][schema-generation],
+or used client-side, as described here.
+
+When used client-side, Core API allows for *dynamically driven client libraries*
+that can interact with any API that exposes a supported schema or hypermedia
+format.
+
+Using a dynamically driven client has a number of advantages over interacting
+with an API by building HTTP requests directly.
+
+#### More meaningful interaction
+
+API interactions are presented in a more meaningful way. You're working at
+the application interface layer, rather than the network interface layer.
+
+#### Resilience & evolvability
+
+The client determines what endpoints are available, what parameters exist
+against each particular endpoint, and how HTTP requests are formed.
+
+This also allows for a degree of API evolvability. URLs can be modified
+without breaking existing clients, or more efficient encodings can be used
+on-the-wire, with clients transparently upgrading.
+
+#### Self-descriptive APIs
+
+A dynamically driven client is able to present documentation on the API to the
+end user. This documentation allows the user to discover the available endpoints
+and parameters, and better understand the API they are working with.
+
+Because this documentation is driven by the API schema it will always be fully
+up to date with the most recently deployed version of the service.
+
+---
+
+# Command line client
+
+The command line client allows you to inspect and interact with any API that
+exposes a supported schema format.
+
+## Getting started
+
+To install the Core API command line client, use `pip`.
+
+Note that the command-line client is a separate package to the
+python client library. Make sure to install `coreapi-cli`.
+
+ $ pip install coreapi-cli
+
+To start inspecting and interacting with an API the schema must first be loaded
+from the network.
+
+ $ coreapi get http://api.example.org/
+
+ snippets: {
+ create(code, [title], [linenos], [language], [style])
+ destroy(pk)
+ highlight(pk)
+ list([page])
+ partial_update(pk, [title], [code], [linenos], [language], [style])
+ retrieve(pk)
+ update(pk, code, [title], [linenos], [language], [style])
+ }
+ users: {
+ list([page])
+ retrieve(pk)
+ }
+
+This will then load the schema, displaying the resulting `Document`. This
+`Document` includes all the available interactions that may be made against the API.
+
+To interact with the API, use the `action` command. This command requires a list
+of keys that are used to index into the link.
+
+ $ coreapi action users list
+ [
+ {
+ "url": "http://127.0.0.1:8000/users/2/",
+ "id": 2,
+ "username": "aziz",
+ "snippets": []
+ },
+ ...
+ ]
+
+To inspect the underlying HTTP request and response, use the `--debug` flag.
+
+ $ coreapi action users list --debug
+ > GET /users/ HTTP/1.1
+ > Accept: application/vnd.coreapi+json, */*
+ > Authorization: Basic bWF4Om1heA==
+ > Host: 127.0.0.1
+ > User-Agent: coreapi
+ < 200 OK
+ < Allow: GET, HEAD, OPTIONS
+ < Content-Type: application/json
+ < Date: Thu, 30 Jun 2016 10:51:46 GMT
+ < Server: WSGIServer/0.1 Python/2.7.10
+ < Vary: Accept, Cookie
+ <
+ < [{"url":"http://127.0.0.1/users/2/","id":2,"username":"aziz","snippets":[]},{"url":"http://127.0.0.1/users/3/","id":3,"username":"amy","snippets":["http://127.0.0.1/snippets/3/"]},{"url":"http://127.0.0.1/users/4/","id":4,"username":"max","snippets":["http://127.0.0.1/snippets/4/","http://127.0.0.1/snippets/5/","http://127.0.0.1/snippets/6/","http://127.0.0.1/snippets/7/"]},{"url":"http://127.0.0.1/users/5/","id":5,"username":"jose","snippets":[]},{"url":"http://127.0.0.1/users/6/","id":6,"username":"admin","snippets":["http://127.0.0.1/snippets/1/","http://127.0.0.1/snippets/2/"]}]
+
+ [
+ ...
+ ]
+
+Some actions may include optional or required parameters.
+
+ $ coreapi action users create --param username=example
+
+When using `--param`, the type of the input will be determined automatically.
+
+If you want to be more explicit about the parameter type then use `--data` for
+any null, numeric, boolean, list, or object inputs, and use `--string` for string inputs.
+
+ $ coreapi action users edit --string username=tomchristie --data is_admin=true
+
+## Authentication & headers
+
+The `credentials` command is used to manage the request `Authentication:` header.
+Any credentials added are always linked to a particular domain, so as to ensure
+that credentials are not leaked across differing APIs.
+
+The format for adding a new credential is:
+
+ $ coreapi credentials add
+
+For instance:
+
+ $ coreapi credentials add api.example.org "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
+
+The optional `--auth` flag also allows you to add specific types of authentication,
+handling the encoding for you. Currently only `"basic"` is supported as an option here.
+For example:
+
+ $ coreapi credentials add api.example.org tomchristie:foobar --auth basic
+
+You can also add specific request headers, using the `headers` command:
+
+ $ coreapi headers add api.example.org x-api-version 2
+
+For more information and a listing of the available subcommands use `coreapi
+credentials --help` or `coreapi headers --help`.
+
+## Codecs
+
+By default the command line client only includes support for reading Core JSON
+schemas, however it includes a plugin system for installing additional codecs.
+
+ $ pip install openapi-codec jsonhyperschema-codec hal-codec
+ $ coreapi codecs show
+ Codecs
+ corejson application/vnd.coreapi+json encoding, decoding
+ hal application/hal+json encoding, decoding
+ openapi application/openapi+json encoding, decoding
+ jsonhyperschema application/schema+json decoding
+ json application/json data
+ text text/* data
+
+## Utilities
+
+The command line client includes functionality for bookmarking API URLs
+under a memorable name. For example, you can add a bookmark for the
+existing API, like so...
+
+ $ coreapi bookmarks add accountmanagement
+
+There is also functionality for navigating forward or backward through the
+history of which API URLs have been accessed.
+
+ $ coreapi history show
+ $ coreapi history back
+
+For more information and a listing of the available subcommands use
+`coreapi bookmarks --help` or `coreapi history --help`.
+
+## Other commands
+
+To display the current `Document`:
+
+ $ coreapi show
+
+To reload the current `Document` from the network:
+
+ $ coreapi reload
+
+To load a schema file from disk:
+
+ $ coreapi load my-api-schema.json --format corejson
+
+To dump the current document to console in a given format:
+
+ $ coreapi dump --format openapi
+
+To remove the current document, along with all currently saved history,
+credentials, headers and bookmarks:
+
+ $ coreapi clear
+
+---
+
+# Python client library
+
+The `coreapi` Python package allows you to programmatically interact with any
+API that exposes a supported schema format.
+
+## Getting started
+
+You'll need to install the `coreapi` package using `pip` before you can get
+started.
+
+ $ pip install coreapi
+
+In order to start working with an API, we first need a `Client` instance. The
+client holds any configuration around which codecs and transports are supported
+when interacting with an API, which allows you to provide for more advanced
+kinds of behaviour.
+
+ import coreapi
+ client = coreapi.Client()
+
+Once we have a `Client` instance, we can fetch an API schema from the network.
+
+ schema = client.get('https://api.example.org/')
+
+The object returned from this call will be a `Document` instance, which is
+the internal representation of the interface that we are interacting with.
+
+Now that we have our schema `Document`, we can now start to interact with the API:
+
+ users = client.action(schema, ['users', 'list'])
+
+Some endpoints may include named parameters, which might be either optional or required:
+
+ new_user = client.action(schema, ['users', 'create'], params={"username": "max"})
+
+## Codecs
+
+Codecs are responsible for encoding or decoding Documents.
+
+The decoding process is used by a client to take a bytestring of an API schema
+definition, and returning the Core API `Document` that represents that interface.
+
+A codec should be associated with a particular media type, such as `'application/coreapi+json'`.
+
+This media type is used by the server in the response `Content-Type` header,
+in order to indicate what kind of data is being returned in the response.
+
+#### Configuring codecs
+
+The codecs that are available can be configured when instantiating a client.
+The keyword argument used here is `decoders`, because in the context of a
+client the codecs are only for *decoding* responses.
+
+In the following example we'll configure a client to only accept `Core JSON`
+and `JSON` responses. This will allow us to receive and decode a Core JSON schema,
+and subsequently to receive JSON responses made against the API.
+
+ from coreapi import codecs, Client
+
+ decoders = [codecs.CoreJSONCodec(), codecs.JSONCodec()]
+ client = Client(decoders=decoders)
+
+#### Loading and saving schemas
+
+You can use a codec directly, in order to load an existing schema definition,
+and return the resulting `Document`.
+
+ input_file = open('my-api-schema.json', 'rb')
+ schema_definition = input_file.read()
+ codec = codecs.CoreJSONCodec()
+ schema = codec.load(schema_definition)
+
+You can also use a codec directly to generate a schema definition given a `Document` instance:
+
+ schema_definition = codec.dump(schema)
+ output_file = open('my-api-schema.json', 'rb')
+ output_file.write(schema_definition)
+
+## Transports
+
+Transports are responsible for making network requests. The set of transports
+that a client has installed determines which network protocols it is able to
+support.
+
+Currently the `coreapi` library only includes an HTTP/HTTPS transport, but
+other protocols can also be supported.
+
+#### Configuring transports
+
+The behaviour of the network layer can be customized by configuring the
+transports that the client is instantiated with.
+
+ import requests
+ from coreapi import transports, Client
+
+ credentials = {'api.example.org': 'Token 3bd44a009d16ff'}
+ transports = transports.HTTPTransport(credentials=credentials)
+ client = Client(transports=transports)
+
+More complex customizations can also be achieved, for example modifying the
+underlying `requests.Session` instance to [attach transport adaptors][transport-adaptors]
+that modify the outgoing requests.
+
+[heroku-api]: https://devcenter.heroku.com/categories/platform-api
+[heroku-example]: http://www.coreapi.org/tools-and-resources/example-services/#heroku-json-hyper-schema
+[core-api]: http://www.coreapi.org/
+[schema-generation]: ../api-guide/schemas.md
+[transport-adaptors]: http://docs.python-requests.org/en/master/user/advanced/#transport-adapters
diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md
index 3df95f0b2..bc1431cfc 100644
--- a/docs/topics/browsable-api.md
+++ b/docs/topics/browsable-api.md
@@ -163,4 +163,4 @@ Better support for autocomplete inputs is planned in future versions.
[bcomponentsnav]: http://getbootstrap.com/2.3.2/components.html#navbar
[autocomplete-packages]: https://www.djangopackages.com/grids/g/auto-complete/
[django-autocomplete-light]: https://github.com/yourlabs/django-autocomplete-light
-[django-autocomplete-light-install]: http://django-autocomplete-light.readthedocs.org/en/latest/#install
+[django-autocomplete-light-install]: https://django-autocomplete-light.readthedocs.io/en/master/install.html
diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md
index c9626ebff..ed7717ae2 100644
--- a/docs/topics/contributing.md
+++ b/docs/topics/contributing.md
@@ -61,6 +61,7 @@ To run the tests, clone the repository, and then:
# Setup the virtual environment
virtualenv env
source env/bin/activate
+ pip install django
pip install -r requirements.txt
# Run the tests
@@ -205,7 +206,7 @@ If you want to draw attention to a note or warning, use a pair of enclosing line
[pep-8]: http://www.python.org/dev/peps/pep-0008/
[travis-status]: ../img/travis-status.png
[pull-requests]: https://help.github.com/articles/using-pull-requests
-[tox]: http://tox.readthedocs.org/en/latest/
+[tox]: https://tox.readthedocs.io/en/latest/
[markdown]: http://daringfireball.net/projects/markdown/basics
[docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs
[mou]: http://mouapp.com/
diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md
index e7d2cde0c..ef4d2b4a8 100644
--- a/docs/topics/documenting-your-api.md
+++ b/docs/topics/documenting-your-api.md
@@ -38,6 +38,34 @@ Both this package and DRF docs are fully documented, well supported, and come hi
---
+### DRF AutoDocs
+
+Oleksander Mashianovs' [DRF Auto Docs][drfautodocs-repo] automated api renderer.
+
+Collects almost all the code you written into documentation effortlessly.
+
+Supports:
+
+ * functional view docs
+ * tree-like structure
+ * Docstrings:
+ * markdown
+ * preserve space & newlines
+ * formatting with nice syntax
+ * Fields:
+ * choices rendering
+ * help_text (to specify SerializerMethodField output, etc)
+ * smart read_only/required rendering
+ * Endpoint properties:
+ * filter_backends
+ * authentication_classes
+ * permission_classes
+ * extra url params(GET params)
+
+
+
+---
+
#### Apiary
There are various other online tools and services for providing API documentation. One notable service is [Apiary][apiary]. With Apiary, you describe your API using a simple markdown-like syntax. The generated documentation includes API interaction, a mock server for testing & prototyping, and various other tools.
@@ -77,7 +105,7 @@ If the python `markdown` library is installed, then [markdown syntax][markdown]
[ref]: http://example.com/activating-accounts
"""
-Note that one constraint of using viewsets is that any documentation be used for all generated views, so for example, you cannot have differing documentation for the generated list view and detail view.
+Note that when using viewsets the basic docstring is used for all generated views. To provide descriptions for each view, such as for the the list and retrieve views, use docstring sections as described in [Schemas as documentation: Examples][schemas-examples].
#### The `OPTIONS` method
@@ -109,6 +137,7 @@ To implement a hypermedia API you'll need to decide on an appropriate media type
[drfdocs-repo]: https://github.com/ekonstantinidis/django-rest-framework-docs
[drfdocs-website]: http://www.drfdocs.com/
[drfdocs-demo]: http://demo.drfdocs.com/
+[drfautodocs-repo]: https://github.com/iMakedonsky/drf-autodocs
[django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger
[swagger]: https://developers.helloreverb.com/swagger/
[rest-framework-docs]: https://github.com/marcgibbons/django-rest-framework-docs
@@ -119,3 +148,4 @@ To implement a hypermedia API you'll need to decide on an appropriate media type
[image-django-rest-swagger]: ../img/django-rest-swagger.png
[image-apiary]: ../img/apiary.png
[image-self-describing-api]: ../img/self-describing.png
+[schemas-examples]: api-guide/schemas/#examples
diff --git a/docs/topics/funding.md b/docs/topics/funding.md
index 7857f8658..91099cb3f 100644
--- a/docs/topics/funding.md
+++ b/docs/topics/funding.md
@@ -8,6 +8,22 @@ if (window.location.hostname == "www.django-rest-framework.org") {
+
+
+
-By taking out a paid plan you'll be directly contributing towards making these features happen.
+---
+
+## Our sponsors
+
+
+
+
diff --git a/docs/topics/html-and-forms.md b/docs/topics/html-and-forms.md
index 6660607fe..f77ae3af7 100644
--- a/docs/topics/html-and-forms.md
+++ b/docs/topics/html-and-forms.md
@@ -108,7 +108,7 @@ Let's take a look at how to render each of the three available template packs. F
class LoginSerializer(serializers.Serializer):
email = serializers.EmailField(
max_length=100,
- style={'placeholder': 'Email'}
+ style={'placeholder': 'Email', 'autofocus': True}
)
password = serializers.CharField(
max_length=100,
@@ -207,9 +207,9 @@ Field templates can also use additional style properties, depending on their typ
The complete list of `base_template` options and their associated style options is listed below.
-base_template | Valid field types | Additional style options
+base_template | Valid field types | Additional style options
----|----|----
-input.html | Any string, numeric or date/time field | input_type, placeholder, hide_label
+input.html | Any string, numeric or date/time field | input_type, placeholder, hide_label, autofocus
textarea.html | `CharField` | rows, placeholder, hide_label
select.html | `ChoiceField` or relational field types | hide_label
radio.html | `ChoiceField` or relational field types | inline, hide_label
diff --git a/docs/topics/kickstarter-announcement.md b/docs/topics/kickstarter-announcement.md
index 78c5cce6f..6b7b428d1 100644
--- a/docs/topics/kickstarter-announcement.md
+++ b/docs/topics/kickstarter-announcement.md
@@ -102,7 +102,7 @@ Our gold sponsors include companies large and small. Many thanks for their signi
### Silver sponsors
-The serious financial contribution that our silver sponsors have made is very much appreciated. I'd like to say a particular thank you to individuals who have choosen to privately support the project at this level.
+The serious financial contribution that our silver sponsors have made is very much appreciated. I'd like to say a particular thank you to individuals who have chosen to privately support the project at this level.
+ 
+ 
+ 
+ 
+