Creación de acciones personalizadas en Django REST Framework

Clase 14 de 21 • Curso de Django Rest Framework

Resumen

Al crear APIs en Django REST Framework, no solo trabajamos con URLs para recursos, sino también con acciones que permiten ejecutar operaciones específicas, como el pago de una tarjeta o, en este caso, gestionar las vacaciones de un doctor.

¿Cómo agregar un campo para controlar el estado de vacaciones en un modelo?

En el modelo Doctor, añadimos el campo is_on_vacation, que será un campo booleano con valor predeterminado False.
Creamos las migraciones con manage.py makemigrations y luego ejecutamos migrate para aplicar los cambios en la base de datos.

¿Cómo crear una acción personalizada para activar o desactivar vacaciones?

En los ViewSets de Django REST Framework, las acciones personalizadas se crean con el decorador @action. Importamos el decorador desde rest_framework.decorators.
Definimos un método llamado toggle_vacation con el decorador y especificamos que solo se permitirá el método POST.
El decorador también necesita el parámetro detail=True para que la acción se aplique a un recurso específico, como un doctor identificado por su ID en la URL.

¿Cómo implementar la lógica para alternar el estado de vacaciones?

Utilizamos el método get_object() del ViewSet para obtener el objeto Doctor actual.
La lógica alterna entre el valor True y False para el campo is_on_vacation. Si está en True, lo cambia a False y viceversa.
Se guarda el objeto Doctor y se retorna una respuesta utilizando Response para informar el estado actualizado.

¿Cómo mejorar la idempotencia y claridad del endpoint?

En lugar de alternar entre True y False, creamos dos acciones separadas: una para activar vacaciones (set_on_vacation) y otra para desactivarlas (set_off_vacation).
Esto asegura que cada petición POST tenga un comportamiento predecible, lo que mejora la idempotencia del endpoint.

¿Cómo ajustar la URL de la acción para mejorar la legibilidad?

Las URLs generadas a partir del nombre del método pueden tener guiones bajos, lo cual no es ideal para SEO y legibilidad. Usamos el parámetro url_path dentro del decorador @action para definir URLs con guiones, por ejemplo, set-on-vacation.

¿Cómo probar las acciones personalizadas?

Desde la interfaz de Django REST Framework, probamos las acciones enviando peticiones POST a las URLs generadas.
Verificamos que los doctores puedan ser marcados como en vacaciones o no, y que el campo is_on_vacation cambie correctamente en la base de datos.

¿Cómo replicar este proceso para otros recursos?

Siguiendo este patrón, podemos crear acciones para otros recursos. Por ejemplo, un paciente puede necesitar obtener un reporte médico en formato JSON, lo cual sería una acción personalizada en el ViewSet de Patient.

Antonio Demarco Bonino

student•

Dejo el reto por aquí:

from rest_framework import viewsets
from rest_framework.decorators import action
from rest_framework.response import Response
from .models import Patient, MedicalHistory
from .serializers import MedicalHistorySerializer

class PatientViewSet(viewsets.ModelViewSet):
    queryset = Patient.objects.all()
    serializer_class = MedicalHistorySerializer  # Se utiliza en las acciones personalizadas

    # Acción personalizada para agregar un nuevo historial clínico
    @action(['POST'], detail=True, url_path='add-medical-history')
    def add_medical_history(self, request, pk=None):
        patient = self.get_object()  # Obtener el paciente por su pk
        data = request.data  # Obtener los datos del historial clínico desde la solicitud
        data['patient'] = patient.id  # Asignar el paciente al historial clínico
        serializer = MedicalHistorySerializer(data=data)
        
        if serializer.is_valid():
            serializer.save()  # Guardar el historial clínico
            return Response({"status": "Medical history added"}, status=201)
        return Response(serializer.errors, status=400)  # Retornar errores si los datos no son válidos

    # Acción personalizada para listar el historial clínico de un paciente
    @action(['GET'], detail=True, url_path='medical-history')
    def list_medical_history(self, request, pk=None):
        patient = self.get_object()  # Obtener el paciente por su pk
        medical_history = MedicalHistory.objects.filter(patient=patient)  # Filtrar el historial clínico por paciente
        serializer = MedicalHistorySerializer(medical_history, many=True)
        return Response(serializer.data)  # Retornar el historial clínico en formato JSON

Juan Camilo Jaramillo Tascón

student•

Para este caso sería bueno si nos puedes compartir el modelo MedicalHistory :), igual gracias por tu aporte.

Andres Trujillo

student•

cool!

Alvaro Emilio Dangond Rojas

student•

from rest_framework import viewsets
from rest_framework.decorators import action
from rest_framework.response import Response
from .models import Patient, Insurance, MedicalRecord
from .serializers import PatientSerializer

# 🧑‍⚕️ ViewSet para gestionar pacientes y consultar su historia clínica
class PatientViewSet(viewsets.ModelViewSet):
    """
    API endpoint que permite ver, crear, actualizar y eliminar pacientes.
    También incluye una acción personalizada para consultar la historia clínica completa.
    """
    queryset = Patient.objects.all()
    serializer_class = PatientSerializer

    @action(detail=True, methods=['get'], url_path='clinical-history')
    def clinical_history(self, request, pk=None):
        """
        Devuelve el reporte de historia clínica del paciente en formato JSON.
        Incluye datos personales, historial médico, seguros y registros clínicos.
        """
        patient = self.get_object()

        # Seguros
        insurances = patient.insurances.all().values(
            'provider', 'policy_number', 'expiration_date'
        )

        # Registros médicos
        records = patient.medical_records.all().values(
            'date', 'diagnosis', 'treatment', 'follow_up_date'
        )

        report = {
            "patient": {
                "id": patient.id,
                "full_name": f"{patient.first_name} {patient.last_name}",
                "date_of_birth": patient.date_of_birth,
                "contact_number": patient.contact_number,
                "email": patient.email,
                "address": patient.address,
                "medical_history": patient.medical_history,
            },
            "insurances": list(insurances),
            "medical_records": list(records),
        }

        return Response(report)
```from rest\_framework import viewsetsfrom rest\_framework.decorators import actionfrom rest\_framework.response import Responsefrom .models import Patient, Insurance, MedicalRecordfrom .serializers import PatientSerializer
\# 🧑‍⚕️ ViewSet para gestionar pacientes y consultar su historia clínicaclass PatientViewSet(viewsets.ModelViewSet):    """    API endpoint que permite ver, crear, actualizar y eliminar pacientes.    También incluye una acción personalizada para consultar la historia clínica completa.    """    queryset = Patient.objects.all()    serializer\_class = PatientSerializer
    @action(detail=True, methods=\['get'], url\_path='clinical-history')    def clinical\_history(self, request, pk=None):        """        Devuelve el reporte de historia clínica del paciente en formato JSON.        Incluye datos personales, historial médico, seguros y registros clínicos.        """        patient = self.get\_object()
        # Seguros        insurances = patient.insurances.all().values(            'provider', 'policy\_number', 'expiration\_date'        )
        # Registros médicos        records = patient.medical\_records.all().values(            'date', 'diagnosis', 'treatment', 'follow\_up\_date'        )
        report = {            "patient": {                "id": patient.id,                "full\_name": f"{patient.first\_name} {patient.last\_name}",                "date\_of\_birth": patient.date\_of\_birth,                "contact\_number": patient.contact\_number,                "email": patient.email,                "address": patient.address,                "medical\_history": patient.medical\_history,            },            "insurances": list(insurances),            "medical\_records": list(records),        }
        return Response(report)

Andres Trujillo

student•

My solutiosn 🫨:

class ListPatientView(viewsets.ModelViewSet):
    serializer_class = PatientSerializer
    queryset = Patient.objects.all()

    @action(["GET"], detail=True, url_path="get-medical-history")
    def get_medical_history(self, request, pk):
        patient = self.get_object()
        return Response({"medical_history": patient.medical_history})

Damian Rengifo

student••

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)

Ernesto Jose Gomez Flores

student•

Solucion al reto:

from rest_framework import viewsets
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework import status

from .serializers import PatientSerializer, MedicalRecordSerializer
from .models import Patient

# Create your views here.


class PatientViewSet(viewsets.ModelViewSet):
    '''
    Vista basada en conjunto de vistas para el modelo Patient.
    Proporciona operaciones CRUD completas para el modelo Patient.
    * Atributos:
        - serializer_class: Serializador para el modelo Patient.
        - queryset: Conjunto de todos los objetos Patient.
    '''
    serializer_class = PatientSerializer
    queryset = Patient.objects.all()

    def get_serializer_class(self):
        '''
        Retorna el serializador apropiado según la acción.
        - Para `add_medical_record`, usa `MedicalRecordSerializer`.
        - Para el resto, usa el `PatientSerializer` por defecto.
        '''
        if self.action == 'add_medical_record':
            return MedicalRecordSerializer
        return super().get_serializer_class()

    #Actions personalizado para agregar un nuevo historial medico
    @action(detail=True, methods=["post"], url_path="add-medical-record")
    def add_medical_record(self, request, pk) -> Response:
        '''
        Agrega un nuevo historial médico a un paciente existente.

        Parámetros:
        - request: Objeto de solicitud HTTP que contiene los datos del historial médico.
        - pk: ID del paciente al que se le agregará el historial médico.

        Retorna:
        - Response: Objeto de respuesta HTTP con el historial médico creado o errores de validación.
        '''
        patient = self.get_object()
        # Obtenemos el serializador a través del método que ya hemos definido
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        serializer.save(patient=patient)
        return Response(serializer.data, status=status.HTTP_201_CREATED)

    #Action personalizado para mostrar el historial medico del paciente en formato JSON
    @action(["GET"], detail=True, url_path="medical-record")
    def medical_record(self, request, pk) -> Response:
        '''
        Recupera el historial médico de un paciente específico.
        Parámetros:
        - request: Objeto de solicitud HTTP.
        - pk: ID del paciente cuyo historial médico se va a recuperar.
        Retorna:
        - Response: Objeto de respuesta HTTP con los datos del historial médico del paciente.
        '''
        patient = self.get_object()
        medical_records = patient.medical_records.all()
        serializer = MedicalRecordSerializer(medical_records, many=True)
        return Response(serializer.data)

Manuel Galindo

student•

Ventajas de utilizar acciones personalizadas en viewsets con Django Rest Framework:

Flexibilidad: Permiten agregar funcionalidades específicas que no están cubiertas por las acciones predeterminadas.
Reutilización de lógica: Facilitan la reutilización de lógica común en diferentes partes de la API.
URLs claras y específicas: Generan rutas URL intuitivas y específicas para las acciones personalizadas.
Mejor organización: Mantienen la lógica relacionada en un solo lugar, mejorando la estructura del código.
Facilitan la extensión: Hacen más sencillo extender la API con nuevas funcionalidades sin modificar las acciones básicas.

Zareth Alvarez

student•

Comparto viewsets de doctors:

from rest_framework import viewsets from .serializers import DoctorSerializer, DepartmentSerializer, DoctorAvailabilitySerializer, MedicalNoteSerializerfrom .models import Doctor, Department, DoctorAvailability, MedicalNote class DoctorViewSet(viewsets.ModelViewSet): serializer_class=DoctorSerializer queryset = Doctor.objects.all()

class DepartmentViewSet(viewsets.ModelViewSet): serializer_class = DepartmentSerializer queryset = Department.objects.all() class DoctorAvailabilityViewSet(viewsets.ModelViewSet): serializer_class = DoctorAvailabilitySerializer queryset = DoctorAvailability.objects.all() class MedicalNoteViewSet(viewsets.ModelViewSet): serializer_class = MedicalNoteSerializer queryset = MedicalNote.objects.all()

Zareth Alvarez

student•

urls. py de doctors de el reto de la clase:

Johan Moises Ariza Mahecha

student•

Comparto mi solución al reto:

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

from .serializers import PatientSerializer, InsuranceSerializer, MedicalRecordSerializer
from .models import Patient, Insurance, MedicalRecord

class PatientViewSets(viewsets.ModelViewSet):
    serializer_class = PatientSerializer
    queryset = Patient.objects.all()

    @action(["GET"], detail=True)
    def show_medical_record(self, requests, pk):
        patient = self.get_object() #Obtenemos el objeto de paciente especifico de esta vista
        medical_record = MedicalRecord.objects.filter(patient = patient)# Traemos todos los medical records relacionados con el paciente
        serializer = MedicalRecordSerializer(medical_record, many=True)#Lo serializamos y lo devolvemos como JSON para ser usado por la API.
        return Response(serializer.data)#Devolvemos los datos de ese JSON
```También el JSON para que se pueda usar en el modelo de Medical Record.

```js
{
        "id": 1,
        "date": "2025-04-10",
        "diagnosis": "Gripe común con síntomas leves como congestión nasal, dolor de garganta y fiebre moderada.",
        "treatment": "Reposo en casa, hidratación abundante, paracetamol cada 8 horas durante 3 días.",
        "follow_up_date": "2025-04-17",
        "patient": 1
    }

Andres Trujillo

student•

Nueva clase, nuevos conocimientos, super genial todo :')

Ederson Felipe Lopez Bolivar

student•

Un ViewSet en Django REST Framework genera automáticamente varias acciones y URLs para manejar operaciones CRUD sobre los recursos. Aquí están las acciones básicas que crea:

Listar: GET /<modelo>/
Crear: POST /<modelo>/
Leer (detalle): GET /<modelo>/<id>/
Actualizar: PUT /<modelo>/<id>/
Parcialmente actualizar: PATCH /<modelo>/<id>/
Eliminar: DELETE /<modelo>/<id>/

Además, si defines acciones personalizadas usando el decorador @action, puedes crear URLs adicionales según la lógica de negocio que necesites, como POST /<modelo>/set_on_vacation/ o similar, dependiendo de cómo lo implementes en tu código. Estas URLs se generan automáticamente siguiendo la convención de nombres y los métodos HTTP permitidos.