You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/topics/3.1-announcement.md
+72-5Lines changed: 72 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ The pagination API has been improved, making it both easier to use, and more pow
10
10
11
11
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.
12
12
13
-
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. Credit to David Cramer for [this blog post](http://cramer.io/2011/03/08/building-cursors-for-the-disqus-api/) on the subject.
13
+
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.
14
14
15
15
#### Pagination controls in the browsable API.
16
16
@@ -34,22 +34,85 @@ We've made it easier to build versioned APIs. Built-in schemes for versioning in
34
34
35
35
When using a URL based scheme, hyperlinked serializers will resolve relationships to the same API version as used on the incoming request.
36
36
37
-
**TODO**: Example.
37
+
For example, when using `NamespaceVersioning`, and the following hyperlinked serializer:
38
+
39
+
class AccountsSerializer(serializer.HyperlinkedModelSerializer):
40
+
class Meta:
41
+
model = Accounts
42
+
fields = ('account_name', 'users')
43
+
44
+
The output representation would match the version used on the incoming request. Like so:
45
+
46
+
GET http://example.org/v2/accounts/10 # Version 'v2'
47
+
48
+
{
49
+
"account_name": "europa",
50
+
"users": [
51
+
"http://example.org/v2/users/12", # Version 'v2'
52
+
"http://example.org/v2/users/54",
53
+
"http://example.org/v2/users/87"
54
+
]
55
+
}
38
56
39
57
## Internationalization
40
58
41
59
REST framework now includes a built-in set of translations, and supports internationalized error responses. This allows you to either change the default language, or to allow clients to specify the language via the `Accept-Language` header.
42
60
43
-
**TODO**: Example.
61
+
You can change the default language by using the standard Django `LANGUAGE_CODE` setting:
62
+
63
+
LANGUAGE_CODE = "es-es"
64
+
65
+
You can turn on per-request language requests by adding `LocalMiddleware` to your `MIDDLEWARE_CLASSES` setting:
66
+
67
+
MIDDLEWARE_CLASSES = [
68
+
...
69
+
'django.middleware.locale.LocaleMiddleware'
70
+
]
71
+
72
+
When per-request internationalization is enabled, client requests will respect the `Accept-Language` header where possible. For example, let's make a request for an unsupported media type:
73
+
74
+
**Request**
75
+
76
+
GET /api/users HTTP/1.1
77
+
Accept: application/xml
78
+
Accept-Language: es-es
79
+
Host: example.org
80
+
81
+
**Response**
44
82
45
-
**TODO**: Credit.
83
+
HTTP/1.0 406 NOT ACCEPTABLE
84
+
85
+
{
86
+
"detail": "No se ha podido satisfacer la solicitud de cabecera de Accept."
87
+
}
88
+
89
+
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].
90
+
91
+
We include built-in translations both for standard exception cases, and for serializer validation errors.
92
+
93
+
The full list of supported languages can be found on our [Transifex project page](https://www.transifex.com/projects/p/django-rest-framework/).
94
+
95
+
If you only wish to support a subset of the supported languages, use Django's standard `LANGUAGES` setting:
96
+
97
+
LANGUAGES = [
98
+
('de', _('German')),
99
+
('en', _('English')),
100
+
]
101
+
102
+
For more details, see the [internationalization documentation](internationalization.md).
103
+
104
+
Many thanks to [Craig Blaszczyk](https://github.com/jakul) for helping push this through.
46
105
47
106
## New field types
48
107
49
108
Django 1.8's new `ArrayField`, `HStoreField` and `UUIDField` are now all fully supported.
50
109
51
110
This work also means that we now have both `serializers.DictField()`, and `serializers.ListField()` types, allowing you to express and validate a wider set of representations.
52
111
112
+
If you're building a new 1.8 project, then you should probably consider using `UUIDField` as the primary keys for all your models. This style will work automatically with hyperlinked serializers, returning URLs in the following style:
The serializer redesign in 3.0 did not include any public API for modifying how ModelSerializer classes automatically generate a set of fields from a given mode class. We've now re-introduced an API for this, allowing you to create new ModelSerializer base classes that behave differently, such as using a different default style for relationships.
@@ -85,6 +148,8 @@ And modify your settings, like so:
85
148
]
86
149
}
87
150
151
+
Thanks go to the latest member of our maintenance team, [José Padilla](https://github.com/jpadilla/), for handling this work and taking on ownership of these packages.
152
+
88
153
# What's next?
89
154
90
155
The next focus will be on HTML renderings of API output and will include:
@@ -93,4 +158,6 @@ The next focus will be on HTML renderings of API output and will include:
93
158
* Filtering controls built-in to the browsable API.
94
159
* An alternative admin-style interface.
95
160
96
-
This will either be made as a single 3.2 release, or split across two separate releases, with the HTML forms and filter controls coming in 3.2, and the admin-style interface coming in a 3.3 release.
161
+
This will either be made as a single 3.2 release, or split across two separate releases, with the HTML forms and filter controls coming in 3.2, and the admin-style interface coming in a 3.3 release.
0 commit comments