Django 1.7 - intro a Django REST Framework

Este POST es una nueva versión de la anterior Introducción a Django REST Framework, actualizada a Django 1.7. Django Rest Framework es una herramienta que nos va a facilitar el desarrollo de APIs para nuestra web. Esto nos permitirá, acceder/modificar/eliminar datos del servidor desde una aplicación móvil, por ejemplo.

Descripción del Tutorial

Para mostrar los principios básicos de Django REST Framework, vamos a crear un pequeño proyecto en el que tenemos un modelo encuesta (survey), y del que queremos proporcionar una API para:

1. Obtener un listado de las encuestas
2. Crear una encuesta
3. Obtener una encuesta concreta
4. Actualizar una encuesta
5. Eliminar una encuesta

Creamos nuestro proyecto

A estas alturas ya deberíamos estar familiarizados con las herramientas virtualenvwrapper, pip y demás que se utilizarán a continuación. De lo contrario, puedes visitar creando un proyecto con Django y virtualenv y VirtualenvWrapper. Creamos el entorno, proyecto y applicación survey donde tendremos nuestro modelo de datos:

miusuario$ mkvirtualenv entornoSurvey (entornoSurvey)$ pip install django (entornoSurvey)$ django-admin.py startproject survey_proj (entornoSurvey)$ cd survey_proj (entornoSurvey)$ chmod u+x manage.py (entornoSurvey)$ ./manage.py startapp survey

Descargamos Django REST Framework y creamos un proyecto para la API

(entornoSurvey)$ pip install djangorestframework (entornoSurvey)$ ./manage.py startapp api

Con esto, deberíamos tener una estructura de directorios como la siguiente:

survey_proj /manage.py /survey_proj /__init__.py /urls.py /wsgi.py /settings.py /survey /__init__.py /admin.py /models.py /tests.py /viewsls.py /api /__init__.py /admin.py /models.py /tests.py /viewsls.py

Añadir las apps, así como django REST framework al fichero settings.py

INSTALLED_APPS = ( ‘django.contrib.admin’, ‘django.contrib.auth’, ‘django.contrib.contenttypes’, ‘django.contrib.sessions’, ‘django.contrib.messages’, ‘django.contrib.staticfiles’, ‘rest_framework’, ‘survey’, ‘api’, )

Modelo de datos de nuestra encuesta

Para poder mostrar datos en nuestra API, primero tendremos que aber que datos queremos mostrar. Cogemos el fichero survey/models.py y lo dejamos así:

from django.db import models class Survey(models.Model): owner = models.CharField(max_length=100) title = models.CharField(max_length=50) question = models.CharField(max_length=300) active = models.BooleanField(default=True) created = models.DateTimeField(auto_now_add=True, auto_now=False) updated = models.DateTimeField(auto_now_add=False, auto_now=True)

Es decir, nuestra encuesta tendra un propietario (para simplificar las cosas durante el ejemplo este campo será un simple CharField), un título, una pregunta, un booleano que nos dirá si está activo o no, y la fecha de creación y actualización. Ahora, démosle acceso a la API a nuestra encuesta.

Creando nuestra API REST

Definiendo las URLs

En primer lugar deberemos definir a través de qué urls queremos acceder a nuestra API, por lo que abrimos el archivo survey_proj/survey_proj/urls.py, y lo modificamos:

from django.conf.urls import patterns, include, url from django.contrib import admin admin.autodiscover() urlpatterns = patterns(”, url(r’^api/’, include(‘api.urls’)), url(r’^admin/’, include(admin.site.urls)), )

Ahora creamos un nuevo archivo urls.py para nuestra API, en survey_proj/api/urls.py y creamos la URLs que usaremos:

from django.conf.urls import patterns, include, url urlpatterns = patterns(‘api.views’, url(r'^surveys/$', ‘survey_list’, name=’survey_list’), url(r'^survey/(?P<pk>[0-9]+)$', ‘survey_details’, name=’survey_details’), )

Con esto, estamos esperando poder acceder a urls del estilo: *http://127.0.0.1:8000/api/surveys/ *http://127.0.0.1:8000/api/survey/1 *http://127.0.0.1:8000/api/survey/32435

Creando un Serializer para nuestro modelo

Los serializers son clases que nos permiten transformar datos de formatos más propios de Django como objetos que extienden de Model o querysets, en formatos más propios del entorno web como puedan ser JSON y XML, y nos permiten hacerlo en ámbas direcciones. En cuanto a la forma de funcionar, tenemos que pensar que los serializers funcionan de un modo muy similar a los Form de Django, pero para nuestra API. De este modo, igual que Django nos proporciona Form y ModelForm, Django REST Framework nos proporciona Serializer y ModelSerializer. La documentación de Django REST Framework es muy completa, y si os interesa entrar al detalle con los Serializers, es el lugar adecuado. Nosotros, vamos directos al ModelSerializer, que nos ahorrará muchas líneas de código. Creamos el archivo survey_proj/api/serializers.py y lo rellenamos con:

from rest_framework import serializers from survey.models import Survey class SurveySerializer(serializers.ModelSerializer): class Meta: model = Survey fields = (‘title’, ‘question’,’owner’, ‘active’)

Lo que estamos creando es una herramienta que nos permite pasar los campos title, question, owner y active de nuestro modelo Survey a JSON (y otros formatos) y viceversa.

Opción 1: Vistas basadas en funciones

Las vistas basadas en funciones utilizan el decorador @api_view como veremos a continuación. Abrimos el archivo survey_proj/api/views.py y definimos 2 funciones, una para cada una de las urls que hemos definido en nuestro módulo url (survey_list y survey_details).

from rest_framework import status from rest_framework.decorators import api_view from rest_framework.response import Response from survey.models import Survey from .serializers import SurveySerializer @api_view([‘GET’, ‘POST’]) def survey_list(request): ”’ List all surveys, or create a new survey ”’ if request.method == ‘GET’: survey = Survey.objects.all() serializer = SurveySerializer(survey, many=True) return Response(serializer.data) elif request.method == ‘POST’: serializer = SurveySerializer(data=request.DATA) if serializer.is_valid(): serializer.save() return Response(serializer.data, status=status.HTTP_201_CREATED) else: return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

@api_view([‘GET’,’PUT’, ‘DELETE’]) def survey_details(request, pk): ”’ Get, update, or delete a specific survey ”’ try: survey = Survey.objects.get(pk=pk) except Survey.DoesNotExist: return Response(status=status.HTTP_404_NOT_FOUND) if request.method == ‘GET’: serializer = SurveySerializer(survey) return Response(serializer.data) if request.method == ‘PUT’: serializer = SurveySerializer(survey, data=request.DATA) if serializer.is_valid(): serializer.save() return Response(serializer.data) else: return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST) elif request.method == ‘DELETE’: survey.delete() return Response(status=status.HTTP_204_NO_CONTENT)

Si miramos detalladamente los métodos, disponemos de dos opciones:

• survey_list:
  • solo nos ofrece opciones GET y POST. El GET nos devuelve todos los objetos Survey, mientras que el post nos permite crear un nuevo objeto Survey.
• survey_details:
  • nos ofrece GET de un Survey concreto
  • nos ofrece PUT (actualización) de un Survey concreto
  • nos ofrece DELETE de un Survey concreto

Probando la API

Para probar la API solo nos queda sincronizar la base de datos y arrancar el servidor de demo:

(entornoSurvey)$ ./manage.py syncdb

Una novedad de Django 1.7, es que ahora incorpora migraciones de forma automática ( para los que vienen de Django 1.6, se usa de forma similar a South). Así que si tocamos el modelo survey despues de crear la base de datos, tendremos que generar las migraciones entre modelos, del siguiente modo:

(entornoSurvey)$ ./manage.py makemigrations (entornoSurvey)$ ./manage.py migrate

En cualquier caso, finalmente ejecutamos el servidor con:

(entornoSurvey)$ ./manage.py runserver

Podemos usar curl o herramientas gráficas como la estupenda extensión de Google Chrome Postman REST Client .

Si utilizais Postman REST Client, podéis importar los ejemplos para la petición GET y POST desde la siguiente colección: https://www.getpostman.com/collections/2e03273d60e1d99dee77

Si testeamos un poco la API que acabamos de crear:

• Petición get de la lista: http://127.0.0.1:8000/api/surveys/
  • de entrada, debería devolvernos un array vacío: []
• Post para crear una Survey: http://127.0.0.1:8000/api/surveys/, pasándole como parámetros del POST ‘owner’, ‘title’, ‘question’ y ‘active’
  • debería devolvernos un JSON con la información introducida:

  { “title”: “The first survey”, “question”: “Are you happy right now?”, “owner”: “Marcus”, “active”: true }

Si volvemos a hacer la petición get, nos devolverá el JSON correspondiente a la survey que acabamos de crear. Podemos seguir haciendo pruebas, pero creo que la idea se entiende.

Opción 2: Vistas basadas en clases

Aún tenemos una forma algo más elegante de definir los métodos que se ejecutarán al acceder a las urls, y que nos permitirán una mayor reusabilidad de código, como podemos ver, más adelante, en la Opción 3: Vistas con clases genéricas y mixins. Básicamente, en lugar de usar el decorador @api_view, podemos definir clases que derivan de la case APIView, en lugar de funciones. De ese modo, podremos definir métodos get, post, etc. para ejecutarse en función del tipo de llamada a nuestra URL. Para nuestro ejemplo, la case view anterior quedaría de la siguiente forma:

from rest_framework import status from rest_framework.response import Response from rest_framework.views import APIView from django.http import Http404 from survey.models import Survey from .serializers import SurveySerializer

class SurveyList(APIView): ”’ List all surveys, or create a new survey ”’ def get(self, request, format=None): survey = Survey.objects.all() serializer = SurveySerializer(survey, many=True) return Response(serializer.data) def post(self, request, format=None): serializer = SurveySerializer(data=request.DATA) if serializer.is_valid(): serializer.save() return Response(serializer.data, status=status.HTTP_201_CREATED) else: return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

class SurveyDetails(APIView): ”’ Get, update, or delete a specific survey ”’ def get_object(self, pk): try: return Survey.objects.get(pk=pk) except Survey.DoesNotExist: raise Http404 def get(self, request, pk, format=None): survey = self.get_object(pk) serializer = SurveySerializer(survey) return Response(serializer.data) def put(self, request, pk, format=None): survey = self.get_object(pk) serializer = SurveySerializer(survey, data=request.DATA) if serializer.is_valid(): serializer.save() return Response(serializer.data) else: return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST) def delete(self, request, pk, format=None): survey = self.get_object(pk) survey.delete() return Response(status=status.HTTP_204_NO_CONTENT)

Para que nuestras URLS accedan a las clases correspondientes, nos faltará un pequeño detalle: modificar el archivo api/urls.py

from django.conf.urls import patterns, include, url from rest_framework.urlpatterns import format_suffix_patterns from . import views urlpatterns = patterns(‘api.views’, url(r'^surveys/$', views.SurveyList.as_view(), name=’survey_list’), url(r'^survey/(?P<pk>[0-9]+)$', views.SurveyDetails.as_view(), name=’survey_details’), ) urlpatterns = format_suffix_patterns(urlpatterns)

Si volvemos a repetir los pasos de Probar la API, todo debería funcionar igual de bien.

Detalle: Sufijos

Probablemente os hayais fijado en que en el archivo urls.py hemos añadido una línea:

urlpatterns = format_suffix_patterns(urlpatterns)

Esto viene relacionado con el argumento format=None que hemos pasado a nuestras vistas en la Opción 2 (también podríamos haberlo hecho en la Opción 1). Añadiendo el suffix_pattern, y pasando el argumento format a las vistas, podemos especificar el tipo de resultado que queremos al llamar a nuestra api, añadiéndole un sufijo a la misma. De este modo, ahora mismo para obtener la lista de surveys podemos obtener los resultados en JSON en las siguientes urls: http://127.0.0.1:8000/api/surveys/ http://127.0.0.1:8000/api/surveys/.json Pero además, de forma automática, podemos obtener un html explicativo de la API en: http://127.0.0.1:8000/api/surveys/.api Utilizando el argumento format podríamos diferenciar el resultado y entregarlo estructurado para otros tipos de formato como XML o YAML.

Opción 3: Vistas con clases genéricas y mixins

Una vez hemos entendido como funcionan las vistas basadas en clases, podemos intuir que gran parte del código se repite. Las operaciones create/retrieve/update/delete que hemos estado usando son muy comunes en cualquier vista que creemos para una API de acceso a modelos. Estos comportamientos comunes han sido implementados a través de mixins.

Usando mixins

Podríamos simplificar nuestra clase SurveyList (no lo hagáis todavía, aún la simplificaremos más, más adelante) de la siguiente forma:

from rest_framework import status, mixins, generics from rest_framework.response import Response from rest_framework.views import APIView from django.http import Http404 from survey.models import Survey from .serializers import SurveySerializer

class SurveyList(mixins.ListModelMixin, mixins.CreateModelMixin, generics.GenericAPIView): ”’ List all surveys, or create a new survey ”’ queryset = Survey.objects.all() serializer_class = SurveySerializer def get(self, request, *args, **kwargs): return self.list(request, *args, **kwargs) def post(self, request, *args, **kwargs): return self.create(request, *args, **kwargs)

Podemos observar como ahora la vista incluye los miins ListModelMixin y CreateModelMixin, y extiende de la vista GenericAPIView. Necesitamos los datos miembro queryset y serializer_class, y para obtener la lista de objetos solo llamamos al método self.list, y de forma análoga, para crearlos llamamos a self.create

Usando clases genéricas basadas en vistas

Con el objetivo de reducir al máximo el código, y dado que hay mecanismos que se repiten habitualmente en las apis (vistas con get para obtener una lista y post para crear nuevos elementos, por ejemplo), Django proporciona clases genéricas de vistas. Vamos a implementar ahora (ahora sí, manos a la obra) nuestro fichero api/views.py mediante clases genéricas:

from rest_framework.generics import ListCreateAPIView, RetrieveUpdateDestroyAPIView from survey.models import Survey from .serializers import SurveySerializer class SurveyMixin(object): queryset = Survey.objects.all() serializer_class = SurveySerializer class SurveyList(SurveyMixin, ListCreateAPIView): pass class SurveyDetails(SurveyMixin, RetrieveUpdateDestroyAPIView): pass

Como podemos ver, creamos un mixin para incluir el queryset y serializer común para SurveyList y SurveyDetails, que extenderán de éste, así como de ListCreateAPIView y RetrieveUpdateDestroyAPIView respectivamente. Las vistas genéricas ya usan internamente los mixins de Django REST Framework, por lo que no es necesario hacer absolutamente NADA más para que todo funcione.

Y eso ha sido todo por ahora, espero que haya resultado útil. ¡Saludos!