Skip to content

Commit 52db57a

Browse files
lovelydinosaurlovelydinosaur
authored
Version 3.6 (encode#4943)
1 parent 537df7a commit 52db57a

File tree

19 files changed

+2420
-2075
lines changed

19 files changed

+2420
-2075
lines changed

‎docs/img/api-docs.gif‎

5.36 MB
Loading

‎docs/img/api-docs.png‎

158 KB
Loading

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -279,7 +279,7 @@ Send a description of the issue via email to [rest-framework-security@googlegrou
279279

280280
## License
281281

282-
Copyright (c) 2011-2016, Tom Christie
282+
Copyright (c) 2011-2017, Tom Christie
283283
All rights reserved.
284284

285285
Redistribution and use in source and binary forms, with or without

‎docs/topics/3.6-announcement.md‎

Lines changed: 133 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,21 @@
1919

2020
# Django REST framework 3.6
2121

22+
The 3.6 release adds two major new features to REST framework.
23+
24+
1. Built-in interactive API documentation support.
25+
2. A new JavaScript client library.
26+
27+
![API Documentation](/img/api-docs.gif)
28+
29+
*Above: The interactive API documentation.*
30+
2231
---
2332

2433
## Funding
2534

26-
The 3.6 release would not have been possible without our [collaborative funding model][funding].
35+
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].
36+
2737
If you use REST framework commercially and would like to see this work continue,
2838
we strongly encourage you to invest in its continued development by
2939
**[signing up for a paid plan][funding]**.
@@ -40,24 +50,141 @@ we strongly encourage you to invest in its continued development by
4050

4151
*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/).*
4252

53+
---
54+
55+
## Interactive API documentation
56+
57+
REST framework's new API documentation supports a number of features:
58+
59+
* Live API interaction.
60+
* Support for various authentication schemes.
61+
* Code snippets for the Python, JavaScript, and Command Line clients.
62+
63+
To install the API documentation, you'll need to include it in your projects URLconf:
64+
65+
from rest_framework.documentation import include_docs_urls
66+
67+
API_TITLE = 'API title'
68+
API_DESCRIPTION = '...'
69+
70+
urlpatterns = [
71+
...
72+
url(r'^docs/', include_docs_urls(title=API_TITLE, description=API_DESCRIPTION))
73+
]
74+
75+
Once installed you should see something a little like this:
76+
77+
![API Documentation](/img/api-docs.png)
78+
79+
We'll likely be making further refinements to the API documentation over the
80+
coming weeks. Keep in mind that this is a new feature, and please do give
81+
us feedback if you run into any issues or limitations.
82+
83+
For more information on documenting your API endpoints see the ["Documenting your API"][api-docs] section.
4384

4485
---
4586

46-
## API documentation
87+
## JavaScript client library
88+
89+
The JavaScript client library allows you to load an API schema, and then interact
90+
with that API at an application layer interface, rather than constructing fetch
91+
requests explicitly.
92+
93+
Here's a brief example that demonstrates:
94+
95+
* Loading the client library and schema.
96+
* Instantiating an authenticated client.
97+
* Making an API request using the client.
4798

48-
...
99+
**index.html**
49100

50-
## JavaScript Client
101+
<html>
102+
<head>
103+
<script src="/static/rest_framework/js/coreapi-0.1.0.js"></script>
104+
<script src="/docs/schema.js' %}"></script>
105+
<script>
106+
const coreapi = window.coreapi
107+
const schema = window.schema
51108

52-
...
109+
// Instantiate a client...
110+
let auth = coreapi.auth.TokenAuthentication({scheme: 'JWT', token: 'xxx'})
111+
let client = coreapi.Client({auth: auth})
112+
113+
// Make an API request...
114+
client.action(schema, ['projects', 'list']).then(function(result) {
115+
alert(result)
116+
})
117+
</script>
118+
</head>
119+
</html>
120+
121+
The JavaScript client library supports various authentication schemes, and can be
122+
used by your project itself, or as an external client interacting with your API.
123+
124+
The client is not limited to usage with REST framework APIs, although it does
125+
currently only support loading CoreJSON API schemas. Support for Swagger and
126+
other API schemas is planned.
127+
128+
For more details see the [JavaScript client library documentation][js-docs].
129+
130+
## Authentication classes for the Python client library
131+
132+
Previous authentication support in the Python client library was limited to
133+
allowing users to provide explicit header values.
134+
135+
We now have better support for handling the details of authentication, with
136+
the introduction of the `BasicAuthentication`, `TokenAuthentication`, and
137+
`SessionAuthentication` schemes.
138+
139+
You can include the authentication scheme when instantiating a new client.
140+
141+
auth = coreapi.auth.TokenAuthentication(scheme='JWT', token='xxx-xxx-xxx')
142+
client = coreapi.Client(auth=auth)
143+
144+
For more information see the [Python client library documentation][py-docs].
53145

54146
---
55147

56148
## Deprecations
57149

58-
...
150+
### Generating schemas from Router
151+
152+
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
153+
"deprecated" warning.
154+
155+
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.
156+
157+
### DjangoFilterBackend
158+
159+
The 3.5 "pending deprecation" warning of the built-in `DjangoFilterBackend` has now
160+
been escalated to a "deprecated" warning.
161+
162+
You should change your imports and REST framework filter settings as follows:
163+
164+
* `rest_framework.filters.DjangoFilterBackend` becomes `django_filters.rest_framework.DjangoFilterBackend`.
165+
* `rest_framework.filters.FilterSet` becomes `django_filters.rest_framework.FilterSet`.
59166

60167
---
61168

169+
## What's next
170+
171+
There are likely to be a number of refinements to the API documentation and
172+
JavaScript client library over the coming weeks, which could include some of the following:
173+
174+
* Support for private API docs, requiring login.
175+
* File upload and download support in the JavaScript client & API docs.
176+
* Comprehensive documentation for the JavaScript client library.
177+
* Automatically including authentication details in the API doc code snippets.
178+
* Adding authentication support in the command line client.
179+
* Support for loading Swagger and other schemas in the JavaScript client.
180+
* Improved support for documenting parameter schemas and response schemas.
181+
* Refining the API documentation interaction modal.
182+
183+
Once work on those refinements is complete, we'll be starting feature work
184+
on realtime support, for the 3.7 release.
185+
62186
[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors
63187
[funding]: funding.md
188+
[api-docs]: documenting-your-api.md
189+
[js-docs]: api-clients.md#javascript-client-library
190+
[py-docs]: api-clients.md#python-client-library

0 commit comments

Comments
 (0)