Introducción a Django REST framework.

Recientemente se ha liberado la versión 3 de Django Rest soportada principalmente por Tom Christie, un ingeniero británico. Esta versión incluye muchas novedades y suponen un salto de calidad y de madurez en la herramienta.

Algunas de las ventajas que nos ofrece DRF a la hora de implementar APIs son las siguientes:

• API navegable desde el browser lo que agiliza el trabajo de los desarrolladores
• Integración con autenticación basada en OAuth1a o OAuth2.
• Serialización de datos a partir de ORM u otros orígenes.
• Muy buena documentación y una amplia comunidad al ser open source.
• Empresas como Red Hat, Heroku o Mozilla lo usan.

A continuación vamos a hacer un breve repaso de la estructura fundamental de DRF y como empezar a usarlo en nuestro proyecto django.

Instalación de DRF

La forma más cómoda de instalar DRF es usar pip la herramienta de instalación de paquetes python, aunque también podemos descargarlo directamente de la web. Para obtener la última versión:

console

$ pip install djangorestframework

A continuación iremos a los settings de django y añadiremos el app a la lista de installed apps:

INSTALLED_APPS = (
    ...
    'rest_framework',
)

También podemos declarar en los settings de django el diccionario REST_FRAMEWORK donde podremos añadir optativamente múltiples opciones de configuración de DRF, veremos alguna más adelante.

REST_FRAMEWORK = {
}

Ya podremos importar funcionalidad de DRF en nuestro proyecto django.

Estructura básica

DRF se basa fundamentalmente en 3 componentes: los serializadores, las vistas y los routers. Vamos a describir brevemente la misión de cada uno antes de abordar en pequeño ejemplo.

• Los routers son una herramienta que nos permiten definir las urls de nuestro API de una manera sencilla y ordenada. Básicamente nos permiten definir limpiamente qué método de una class view se ejecutará al llegar una petición HTTP contra un path concreto usando un verbo HTTP u otro. En resumen nos permiten definir cómodamente conjuntos de urls y nos encaminan a nuestros métodos en función del verbo HTTP (GET, POST, PUT, PATCH...).
• Las views no son más que extensiones de las class-view de django, pero de alguna forma vitaminadas para simplificarnos el enganche con los routers, los serializadores y los modelos y en lugar de renderizar un html como respuesta devolver de forma sencilla un json, xml u otra estructura de datos que nos interese que devuelva nuestra API. En este punto prima la convención sobre la configuración pudiendo basarnos en las clases standards de la librería para describir en muy pocas líneas nuestra API.
• Por último, los serializadores nos permiten definir al detalle cómo serán las respuestas que devolverá nuestro API y cómo procesaremos el contenido de las peticiones que nos lleguen.

Ejemplo

Vamos a escribir un pequeño ejemplo, donde veremos cómo en pocas líneas, haciendo uso de los mecanismos y convenciones de DRF, podemos crear y exponer un API de usuarios. El ejemplo completo está disponible en github.

Serializador

En este caso definimos un serializador asociado al modelo User de django que modeliza los usuarios de la aplicación.

De todos los posibles campos del modelo user le decimos a nuestro serializador que sólo use el nombre de usuario y el correo electrónico.

from django.contrib.auth.models import User
from rest_framework import serializers
class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ('username', 'email')

Vista

A continuación definimos una vista que haga uso de nuestro serializador, para simplificar este paso DRF nos ofrece la clase ModelViewSet de la que podemos heredar y que nos hará todo el trabajo de recuperación y renderización de la información.

Lo único que tendremos que indicar es qué queryset queremos que use para consultar contra la base de datos y que serializador para renderizar el resultado, en este caso le indicaremos el serializador que hemos definido en el paso anterior.

from django.contrib.auth.models import User
from rest_framework import viewsets
from tutorial.quickstart.serializers import UserSerializer
class UserViewSet(viewsets.ModelViewSet):
    """
    API endpoint that allows users to be viewed or edited.
    """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer

Es interesante destacar que en el parámetro queryset podemos pasar cualquier objeto de tipo queryset, lo que nos permite de manera muy sencilla hacer filtros, ordenar o cualquier otra de las operaciones ofrecidas por los queryset de django.

Router

Por último, debemos de definir nuestro router que será el componente dedicado a exponer nuestra API en una url concreta y a redirigir las peticiones que lleguen a su correspondiente vista. En este caso vamos a exponer nuestro API de user en /users.

from django.conf.urls import url, include
from rest_framework import routers
from tutorial.quickstart import views
router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet)
urlpatterns = [
    url(r'^', include(router.urls))
]

Configuración

Las opciones de configuración son muy extensas y queda fuera de este artículo comentarlas todas, en cualquier caso la documentación oficial es muy completa en este sentido.

Algunas de las opciones de configuración soportadas son el tamaño de página, la versión del API que se servirá por defecto, el formato que queremos usar para la fecha y hora, o la forma en la que manejaremos las excepciones que se produzcan.

A modo de ejemplo vamos a ver cómo configuraríamos el tamaño de página máximo de los resultados que devolvería el API.

Como ya comentamos anteriormente, en nuestros settings de django tenemos la posibilidad de definir el diccionario REST_FRAMEWORK y aquí dentro podremos incluir todas las configuraciones globales para DRF.

En el caso del tamaño de página simplemente añadiremos un elemento donde la clave debe ser ‘PAGE_SIZE’ y el valor un número entero que indique el número de elementos por página que deseamos:

REST_FRAMEWORK = {
    'PAGE_SIZE': 10
}

Conclusión

DRF es una herramienta muy potente, completa y madura, que nos permite construir APIs de una manera rápida y sencilla. Antepone la convención sobre la configuración, pero las opciones de configuración son muy extensas y bien documentadas.

Una de las formas más sencillas y completas de empezar a usar y aprender DRF es seguir el tutorial que nos ofrecen en la página oficial, gracias a él en poco minutos tendremos una prueba de concepto funcionando y entenderemos mejor las ventajas del framework.

Y en nuestro repositorio de GitHub tenemos disponible el código de ejemplo del tutorial.

Sin duda si nos planteamos construir un API REST en Python, DRF es una de las mejores opciones por las que podemos optar. En Paradigma lo hemos usado ampliamente en varios proyectos de gran envergadura y hemos conseguido agilizar el desarrollo, minimizar el código disminuyendo en consecuencia el número de errores y facilitando la mantenibilidad.