Acciones personalizadas en ViewSets REST

Contenido del curso

Fundamentos de Django Rest Framework

Vistas y Endpoints

Serializadores Avanzados

Testing y Desempeño

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:0012:57

Acciones personalizadas en ViewSets REST

Curso de Django Rest Framework

Clase 14 de 21

Clase 14 / 21

Recursos

Las APIs REST no se limitan a exponer recursos: también permiten ejecutar acciones específicas sobre ellos, como marcar a un doctor en vacaciones o generar un reporte. Con Django REST Framework puedes crear estas acciones personalizadas dentro de un ViewSet usando el decorador @action, manteniendo tu código limpio y reutilizable.

Esta guía te muestra cómo añadir endpoints personalizados a un recurso, respetar el principio de idempotencia y ajustar las URLs para que sean legibles y amigables con SEO.

¿Qué son las acciones en un ViewSet de Django REST Framework?

Una acción es un endpoint adicional dentro de un ViewSet que ejecuta lógica de negocio específica sobre un recurso, más allá del clásico CRUD. Piensa en cosas como pagar con una tarjeta, generar una historia clínica o, en el ejemplo que vamos a construir, marcar a un doctor como si estuviera de vacaciones.

¿Qué hace el decorador @action en Django REST Framework? Convierte un método de tu ViewSet en un endpoint extra. Tú defines qué métodos HTTP acepta y si aplica al detalle (un solo objeto) o a la lista completa.

¿Cómo preparar el modelo antes de crear la acción? [01:05]

Antes de tocar el ViewSet, necesitas el campo en el modelo. En Doctor agregamos un booleano:

python is_on_vacation = models.BooleanField(default=False)

Luego corres las migraciones desde la consola:

python manage.py makemigrations.
python manage.py migrate.

Con esto el campo queda disponible y por defecto todos los doctores arrancan fuera de vacaciones.

¿Cómo se usa el decorador @action para crear endpoints personalizados?

El decorador @action se importa desde rest_framework.decorators y se aplica sobre un método nuevo dentro del ViewSet. Recibe parámetros que definen el comportamiento del endpoint.

python from rest_framework.decorators import action from rest_framework.response import Response

@action(detail=True, methods=['post'], url_path='set-on-vacation') def set_on_vacation(self, request, pk=None): doctor = self.get_object() doctor.is_on_vacation = True doctor.save() return Response({'status': 'El doctor está en vacaciones'})

Dos parámetros son clave:

detail=True indica que la acción opera sobre un solo objeto y requiere un ID en la URL.
methods=['post'] restringe el endpoint a peticiones POST únicamente.

¿Por qué usar self.get_object en lugar de filtrar manualmente? [03:20]

Dentro del método podrías escribir tu propio filtro con self.queryset.get(pk=pk), pero Django REST Framework ya trae self.get_object(). Este método retorna el objeto de la vista actual y, además, aplica los filtros y validaciones que ya están configurados en el ViewSet.

Reutilizar get_object evita romper funcionalidades que dependen de esos filtros y mantiene tu código alineado con el comportamiento del framework. Es uno de esos detalles que diferencian una API que escala de una que se vuelve frágil con cada feature nuevo.

¿Por qué los endpoints REST deben ser idempotentes?

La idempotencia significa que ejecutar la misma petición varias veces produce el mismo resultado. Si un cliente reintenta un request por una falla de red, el estado final no debe cambiar entre intentos.

En la primera versión del código se planteó un toggle_vacation que alternaba entre true y false en cada POST. El problema: si el request falla y se reintenta, nadie sabe en qué estado quedó el recurso. Eso confunde a los desarrolladores que consumen la API.

¿Qué significa que un endpoint sea idempotente? Que puedes ejecutarlo una o cien veces y el resultado final será el mismo. Por eso conviene separar acciones explícitas como set-on-vacation y set-off-vacation en lugar de un toggle.

La solución fue dividir la lógica en dos acciones claras:

set_on_vacation siempre deja is_on_vacation = True.
set_off_vacation siempre deja is_on_vacation = False.

Así cada endpoint tiene un único resultado predecible. Si el frontend necesita un botón tipo toggle, puede decidir cuál de los dos endpoints llamar según el estado actual.

¿Cómo personalizar la URL de una acción con url_path?

Por defecto, Django REST Framework genera la URL de la acción tomando el nombre del método. Si tu método se llama set_on_vacation, la URL queda como /set_on_vacation/ con guiones bajos.

Esto no es ideal: las URLs con guiones medios son más legibles y amigables para SEO. Para ajustarlo, agrega el parámetro url_path al decorador:

python @action(detail=True, methods=['post'], url_path='set-on-vacation') def set_on_vacation(self, request, pk=None): ...

Con ese cambio la URL pasa a ser /doctors/{id}/set-on-vacation/, mucho más limpia y consistente con las convenciones web.

¿Cómo probar la acción desde el navegador? [09:40]

Django REST Framework genera automáticamente un botón Extra Actions en la interfaz navegable cuando entras al detalle de un recurso. Al abrir el doctor Fernando Martínez aparecen las opciones Set on vacation y Set off vacation.

Si intentas un GET sobre la URL recibirás un error de método no permitido, porque la acción solo acepta POST. Al hacer el POST correcto, la respuesta devuelve el mensaje configurado y el campo is_on_vacation se actualiza en la instancia.

Un detalle a cuidar: cuando duplicas una acción para crear su versión opuesta, revisa el mensaje de respuesta. En el ejemplo, copiar set_on_vacation y olvidar cambiar el texto hizo que el endpoint de off siguiera respondiendo "El doctor está en vacaciones". Pequeño descuido, gran confusión para quien consume la API.

Reto: crea una acción para reportar la historia clínica

Ahora te toca aplicar lo aprendido. Dentro del recurso Patient, crea una nueva acción que devuelva el reporte de la historia clínica de un paciente en formato JSON. Define bien si debe ser detail=True, qué método HTTP acepta y cómo nombrar el url_path.

¿Qué otras acciones se te ocurren para una API médica? Cuéntame en los comentarios cómo resolviste el reto.

Damian Rengifo

Hace 10 meses•editado

Esta fue mi solucion al reto, fue un poco complicado por que tuve que investigar como cambiar correctamente el serializer segun la accion

from rest_framework import viewsets, status

from rest_framework.response import Response

from rest_framework.decorators import action

from .serializers import PatientSerializers, InsuranceSerializers, MedicalRecordSerializers

from .models import Patient, Insurance, MedicalRecord

class PatientViewSet(viewsets.ModelViewSet):

"""

Endpoints GET, PUT, PATCH, POST AND DELETE for the manage of the patients

"""

serializer_class = PatientSerializers

queryset = Patient.objects.all()

def get_serializer_class(self):

if self.action == 'generate_medical_history':

return MedicalRecordSerializers

return super().get_serializer_class()

@action(['POST'], detail=True, url_path='generate-medical-history')

def generate_medical_history(self, request, pk) -> Response:

'''

Action for create a medical history for a patient created recently with the method POST in this endpoint.

Args: pk(id_patient) pk of the patient created recently

'''

patient = self.get_object()

data = request.data.copy()

data['patient'] = patient.id

serializador = MedicalRecordSerializers(data=data)

serializador.is_valid(raise_exception=status.HTTP_422_UNPROCESSABLE_ENTITY)

serializador.save()

return Response(serializador.data, status=status.HTTP_201_CREATED)

@action(['GET'], detail=True, url_path='consult-medic-history')

def consult_medic_history(self, request, pk) -> Response:

'''

Action for consult the medic history of a pacient

args = pk(patient_id), with this argument you can obtain the medical records of the patient with that pk

'''

patient = self.get_object()

medical_records = MedicalRecord.objects.filter(patient=patient)

serializador = MedicalRecordSerializers(medical_records, many=True)

code = status.HTTP_200_OK if medical_records.count() > 0 else status.HTTP_204_NO_CONTENT

return Response(serializador.data, status=code)

Comentarios (11)11 comentarios

Antonio Demarco Bonino

Hace 2 años

Juan Camilo Jaramillo Tascón

Andres Trujillo

Alvaro Emilio Dangond Rojas

Hace un año

Johan Moises Ariza Mahecha

Francesc Bassas Serramia

Hace 5 meses

Jarol Jiménez

Hace 6 meses

Ernesto Jose Gomez Flores

Manuel Galindo

Zareth Alvarez

Ederson Felipe Lopez Bolivar

Fundamentos de Django Rest Framework

Django REST Framework para APIs escalables

Qué es una API REST y cómo usar JSON

Configuración de Django REST Framework paso a paso

Django Rest: qué reutiliza de Django

Serializers Django: modelos a JSON fácil

Listado de pacientes con serializers en DRF

POST y GET en el mismo endpoint con Django REST

CRUD completo con PUT y DELETE en Django Rest

Cómo probar APIs con Postman y curl

Django Rest Framework: de funciones a vistas genéricas

Vistas genéricas en Django Rest Framework

Documentación automática de APIs con drf-spectacular

Vistas y Endpoints

ViewSets vs APIView: refactor automático de URLs

Acciones personalizadas en ViewSets REST

Autenticación y permisos en Django Rest Framework

Validaciones custom en Django Rest Framework

Serializadores Avanzados

Serializadores anidados en Django REST Framework

Calcular campos dinámicos con SerializerMethodField

Endpoint anidado para citas en Django REST

Testing y Desempeño

Tests de API con APIClient en Django

Throttling en Django Rest para evitar ataques DOS

Acciones personalizadas en ViewSets REST

Progreso del curso

Fundamentos de Django Rest Framework

Vistas y Endpoints

Serializadores Avanzados

Testing y Desempeño

Recursos

Recursos