|
| 1 | +# Django REST framework 3.2 |
| 2 | + |
| 3 | +The 3.2 release is the first version to include an admin interface for the browsable API. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +This interface is intended to act as a more user-friendly interface to the API. It can be used either as a replacement to the existing `BrowsableAPIRenderer`, or used together with it, allowing you to switch between the two styles as required. |
| 8 | + |
| 9 | +We've also fixed a huge number of issues, and made numerous cleanups and improvements. |
| 10 | + |
| 11 | +Over the course of the 3.1.x series we've [resolved nearly 600 tickets](https://github.com/tomchristie/django-rest-framework/issues?utf8=%E2%9C%93&q=closed%3A%3E2015-03-05) on our GitHub issue tracker. This means we're currently running at a rate of **closing around 100 issues or pull requests per month**. |
| 12 | + |
| 13 | +None of this would have been possible without the support of our wonderful Kickstarter backers. If you're looking for a job in Django development we'd strongly recommend taking [a look through our sponsors](http://www.django-rest-framework.org/topics/kickstarter-announcement/#sponsors) and finding out who's hiring. |
| 14 | + |
| 15 | +## AdminRenderer |
| 16 | + |
| 17 | +To include `AdminRenderer` simply add it to your settings: |
| 18 | + |
| 19 | + REST_FRAMEWORK = { |
| 20 | + 'DEFAULT_RENDERER_CLASSES': [ |
| 21 | + 'rest_framework.renderers.JSONRenderer', |
| 22 | + 'rest_framework.renderers.AdminRenderer', |
| 23 | + 'rest_framework.renderers.BrowsableAPIRenderer' |
| 24 | + ], |
| 25 | + 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination', |
| 26 | + 'PAGE_SIZE': 100 |
| 27 | + } |
| 28 | + |
| 29 | +There are some limitations to the `AdminRenderer`, in particular it is not yet able to handle list or dictionary inputs, as we do not have any HTML form fields that support those. |
| 30 | + |
| 31 | +Also note that this is an initial release and we do not yet have a public API for modifying the behavior or documentation on overriding the templates. |
| 32 | + |
| 33 | +The idea is to get this released to users early, so we can start getting feedback and release a more fully featured version in 3.3. |
| 34 | + |
| 35 | +## Deprecations |
| 36 | + |
| 37 | +There are no new deprecations in 3.2, although a number of existing deprecations have now escalated in line with our deprecation policy. |
| 38 | + |
| 39 | +* `request.DATA` was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of `request.data` instead. |
| 40 | +* `request.FILES` was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of `request.files` instead. |
| 41 | +* `request.QUERY_PARAMS` was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of `request.query_params` instead. |
| 42 | +* The following `ModelSerializer.Meta` options have now been removed: `write_only_fields`, `view_name`, `lookup_field`. Use the more general `extra_kwargs` option instead. |
| 43 | + |
| 44 | +The following pagination view attributes and settings have been moved into attributes on the pagination class since 3.1. Their usage was formerly in 'pending deprecation', and has now escalated to 'deprecated'. They will continue to function but will raise errors. |
| 45 | + |
| 46 | +* `view.paginate_by` - Use `paginator.page_size` instead. |
| 47 | +* `view.page_query_param` - Use `paginator.page_query_param` instead. |
| 48 | +* `view.paginate_by_param` - Use `paginator.page_size_query_param` instead. |
| 49 | +* `view.max_paginate_by` - Use `paginator.max_page_size` instead. |
| 50 | +* `settings.PAGINATE_BY` - Use `paginator.page_size` instead. |
| 51 | +* `settings.PAGINATE_BY_PARAM` - Use `paginator.page_size_query_param` instead. |
| 52 | +* `settings.MAX_PAGINATE_BY` - Use `max_page_size` instead. |
| 53 | + |
| 54 | +## Modifications to list behaviors |
| 55 | + |
| 56 | +There are a couple of bug fixes that are worth calling out as they introduce differing behavior. |
| 57 | + |
| 58 | +These are a little subtle and probably won't affect most users, but are worth understanding before upgrading your project. |
| 59 | + |
| 60 | +### ManyToMany fields and blank=True |
| 61 | + |
| 62 | +We've now added an `allow_empty` argument, which can be used with `ListSerializer`, or with `many=True` relationships. This is `True` by default, but can be set to `False` if you want to disallow empty lists as valid input. |
| 63 | + |
| 64 | +As a follow-up to this we are now able to properly mirror the behavior of Django's `ModelForm` with respect to how many-to-many fields are validated. |
| 65 | + |
| 66 | +Previously a many-to-many field on a model would map to a serializer field that would allow either empty or non-empty list inputs. Now, a many-to-many field will map to a serializer field that requires at least one input, unless the model field has `blank=True` set. |
| 67 | + |
| 68 | +Here's what the mapping looks like in practice: |
| 69 | + |
| 70 | +* `models.ManyToManyField()` → `serializers.PrimaryKeyRelatedField(many=True, allow_empty=False)` |
| 71 | +* `models.ManyToManyField(blank=True)` → `serializers.PrimaryKeyRelatedField(many=True)` |
| 72 | + |
| 73 | +The upshot is this: If you have many to many fields in your models, then make sure you've included the argument `blank=True` if you want to allow empty inputs in the equivalent `ModelSerializer` fields. |
| 74 | + |
| 75 | +### List fields and allow_null |
| 76 | + |
| 77 | +When using `allow_null` with `ListField` or a nested `mant=True` serializer the previous behavior was to allow `null` values as items in the list. The behavior is now to allow `null` values instead of the list. |
| 78 | + |
| 79 | +For example, take the following field: |
| 80 | + |
| 81 | + NestedSerializer(many=True, allow_null=True) |
| 82 | + |
| 83 | +Previously the validation behavior would be: |
| 84 | + |
| 85 | +* `[{…}, null, {…}]` is **valid**. |
| 86 | +* `null` is **invalid**. |
| 87 | + |
| 88 | +Our validation behavior as of 3.2.0 is now: |
| 89 | + |
| 90 | +* `[{…}, null, {…}]` is **invalid**. |
| 91 | +* `null` is **valid**. |
| 92 | + |
| 93 | +If you want to allow `null` child items, you'll need to instead specify `allow_null` on the child class, using an explicit `ListField` instead of `many=True`. For example: |
| 94 | + |
| 95 | + ListField(child=NestedSerializer(allow_null=True)) |
| 96 | + |
| 97 | +## What's next? |
| 98 | + |
| 99 | +The 3.3 release is currently planned for the start of October, and will be the last Kickstarter-funded release. |
| 100 | + |
| 101 | +This release is planned to include: |
| 102 | + |
| 103 | +* Search and filtering controls in the browsable API and admin interface. |
| 104 | +* Improvements and public API for the admin interface. |
| 105 | +* Improvements and public API for our templated HTML forms and fields. |
| 106 | +* Nested object and list support in HTML forms. |
| 107 | + |
| 108 | +Thanks once again to all our sponsors and supporters. |
0 commit comments