The 3.6 release adds two major new features to REST framework.
1. Built-in interactive API documentation support.
2. A new JavaScript client library.
![API Documentation](/img/api-docs.gif)
*Above: The interactive API documentation.*
---
## Funding
The 3.6 release would not have been possible without our [collaborative funding model][funding].
The 3.6 release would not have been possible without our [backing from Mozilla](mozilla-grant.md) to the project, and 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]**.
...
...
@@ -40,24 +50,141 @@ we strongly encourage you to invest in its continued development by
*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), [Machinalis](https://hello.machinalis.co.uk/), [Rollbar](https://rollbar.com), and [MicroPyramid](https://micropyramid.com/django-rest-framework-development-services/).*
---
## Interactive API documentation
REST framework's new API documentation supports a number of features:
* Live API interaction.
* Support for various authentication schemes.
* Code snippets for the Python, JavaScript, and Command Line clients.
To install the API documentation, you'll need to include it in your projects URLconf:
from rest_framework.documentation import include_docs_urls
For more information see the [Python client library documentation][py-docs].
---
## Deprecations
...
### Generating schemas from Router
The 3.5 "pending deprecation" of router arguments for generating a schema view, such as `schema_title`, `schema_url` and `schema_renderers`, have now been escalated to a
"deprecated" warning.
Instead of using `DefaultRouter(schema_title='Example API')`, you should use the `get_schema_view()` function, and include the view explicitly in your URL conf.
### DjangoFilterBackend
The 3.5 "pending deprecation" warning of the built-in `DjangoFilterBackend` has now
been escalated to a "deprecated" warning.
You should change your imports and REST framework filter settings as follows:
The `BasicAuthentication` class can be used to support HTTP Basic Authentication.
auth = coreapi.auth.BasicAuthentication(
username='<username>',
password='<password>'
)
client = coreapi.Client(auth=auth)
## Interacting with the API
Now that we have a client and have fetched our schema `Document`, we can now
start to interact with the API:
users = client.action(schema, ['users', 'list'])
...
...
@@ -330,12 +380,23 @@ There are two separate JavaScript resources that you need to include in your HTM
First, install the API documentation views. These will include the schema resource that'll allow you to load the schema directly from an HTML page, without having to make an asynchronous AJAX call.
url(r'^docs/', include_docs_urls(title='My API service'))
from rest_framework.documentation import include_docs_urls
urlpatterns = [
...
url(r'^docs/', include_docs_urls(title='My API service'))
]
Once the API documentation URLs are installed, you'll be able to include both the required JavaScript resources. Note that the ordering of these two lines is important, as the schema loading requires CoreAPI to already be installed.
If you're using session authentication, and handling login requests using regular HTML forms then you probably won't need an authentication flow for the client. However, if you're using one of the other types of authentication,
A suggested pattern for this would be to initially make an unauthenticated client request to an "obtain token" endpoint
For example, using the "Django REST framework JWT" package
// Globally accessible state
window.client = coreapi.Client()
window.loggedIn = false
function loginUser(username, password) {
let action = ["api-token-auth", "obtain-token"]
let params = {username: "example", email: "example@example.com"}
<spanid="schemeHelpBlock"class="help-block">Either a registered authentication scheme such as <code>Bearer</code>, or a custom schema such as <code>Token</code> or <code>JWT</code>.</span>