Django REST Framework 3.8 est sorti
par Makersquad ·
Date de sortie : 3 avril 2018
Documentation officielle : https://www.django-rest-framework.org/community/release-notes/#38x-series
Cette version de Django REST Framework (DRF) est une version de maintenance : selon l’annonce officielle, elle résout un grand nombre de problèmes ouverts depuis longtemps et pose les bases de changements futurs.
Les nouveautés principales
Nouveau décorateur @action unifié
Les décorateurs @list_route et @detail_route sont fusionnés en un seul décorateur @action. Le paramètre booléen detail indique si l’action s’applique à une instance unique ou à la liste. Les deux anciens décorateurs sont en dépréciation en attente (pending deprecation) : ils seront dépréciés en 3.9 et supprimés en 3.10.
from rest_framework.decorators import action
class UserViewSet(viewsets.ModelViewSet):
@action(detail=True, methods=['post'])
def set_password(self, request, pk=None):
# action sur un objet précis : /users/{pk}/set_password/
...
@action(detail=False)
def recent_users(self, request):
# action sur la collection : /users/recent_users/
...
Pour migrer, remplacez @detail_route par @action(detail=True) et @list_route par @action(detail=False). Ce changement améliore l’introspection des actions d’un viewset et permettra d’afficher les actions supplémentaires dans la Browsable API dans une version future.
Comportement cohérent des champs en lecture seule
Les champs read_only sont désormais toujours exclus des champs modifiables. C’est un changement de comportement incompatible à connaître : auparavant, un champ read_only doté d’une valeur par défaut utilisait cette valeur lors des créations et des mises à jour.
Pour conserver l’ancien comportement, passez la valeur du champ lors de l’appel à save() dans la vue, ou surchargez save(), create() ou update() sur le serializer.
def perform_create(self, serializer):
serializer.save(owner=self.request.user)
La version 3.8.0 corrige aussi le comportement de allow_null avec required=False : sans valeur par défaut explicite, allow_null implique une valeur par défaut None à la sérialisation. Les champs concernés, auparavant omis, apparaissent donc dans la représentation sortante, ce qui peut casser du code qui comptait sur leur absence.
Exclusion d’une vue du schéma généré
Pour retirer une vue de la génération de schéma, l’approche recommandée consiste à assigner schema = None directement sur la vue. Cette méthode remplace le paramètre exclude_from_schema, déprécié dès la version 3.7.
class MyView(APIView):
schema = None # exclut cette vue du schéma généré
Maintenance et correctifs
DRF 3.8 résout un grand nombre de problèmes restés ouverts. La liste complète figure dans les notes de version de la série 3.8.x, qui comprend aussi les correctifs 3.8.1 et 3.8.2.
À retenir
DRF 3.8 est une version de maintenance. Avant de monter de version, vérifiez les champs read_only qui ont une valeur par défaut et migrez vos @list_route et @detail_route vers @action, dépréciés en 3.9 puis supprimés en 3.10.