Endpoint anidado para citas en Django 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:0014:01

Endpoint anidado para citas en Django REST

Curso de Django Rest Framework

Clase 19 de 21

Clase 19 / 21

Recursos

Crear un endpoint anidado en Django REST Framework te permite estructurar URLs que reflejan relaciones reales entre recursos, como un doctor y sus citas médicas. Aquí aprendes a construir un endpoint que liste y cree appointments asociados a un doctor específico, siguiendo principios REST y reutilizando el id del recurso padre.

Por qué usar un endpoint anidado para crear citas

Cuando un recurso depende de otro, anidar la URL aclara la jerarquía y simplifica la lógica del backend. En este caso, una cita siempre pertenece a un doctor, así que la URL /doctors/{id}/appointments/ comunica esa relación de inmediato.

La idea es que un GET a esa ruta devuelva la lista de citas de ese doctor, y un POST cree una nueva cita usando el id del doctor que ya viene en la URL. Esto evita que el cliente pueda manipular el doctor desde el body, algo clave para mantener la integridad de los datos.

¿Qué es un endpoint anidado en REST? Es una URL que expone un recurso hijo bajo el contexto de un recurso padre, por ejemplo /doctors/3/appointments/. Sirve cuando el hijo no tiene sentido fuera del padre.

Cómo definir la action appointments en el ViewSet

Django REST Framework permite agregar rutas personalizadas a un ModelViewSet mediante el decorador @action. Para esta funcionalidad necesitas declarar que la acción acepta tanto GET como POST, y marcarla como vista de detalle porque depende del id de un doctor.

Dentro del viewset de doctores defines un método appointments decorado con @action(detail=True, methods=['GET','POST']). El parámetro detail=True indica que la URL incluirá el pk del doctor, mientras que la lista de métodos habilita ambas operaciones en la misma ruta.

Dentro del método obtienes el doctor con self.get_object(), que aprovecha el queryset del viewset para recuperar la instancia que coincide con el pk recibido. A partir de ahí, ramificas el comportamiento según request.method.

Cómo manejar POST para crear una cita

Para crear el appointment, importas AppointmentSerializer desde bookings.serializers y construyes un diccionario nuevo basado en request.data. La razón de copiar la data en lugar de usarla directamente es forzar el id del doctor desde la URL, así el cliente no puede sobrescribirlo.

Los pasos concretos son:

Copiar request.data en una variable data.
Asignar data['doctor'] = doctor.id, ya que Django REST enlaza relaciones por id.
Instanciar AppointmentSerializer(data=data) pasando el parámetro nombrado data para que el serializer entienda que se trata de información a validar, no de una instancia existente.
Llamar a serializer.is_valid(raise_exception=True) para devolver un error legible si algo no cumple las reglas.
Ejecutar serializer.save() para persistir la cita.
Retornar Response(serializer.data, status=status.HTTP_201_CREATED).

El módulo status se importa desde rest_framework y expone constantes como HTTP_201_CREATED, que hacen el código más legible que escribir el número directamente.

Cómo manejar GET para listar las citas del doctor

Para el GET, filtras el modelo Appointment por el doctor recibido. Importas el modelo con from bookings.models import Appointment y ejecutas Appointment.objects.filter(doctor=doctor).

Luego serializas la lista con AppointmentSerializer(appointments, many=True). El argumento many=True es indispensable cuando pasas un queryset o lista de instancias, porque le indica al serializer que debe iterar y producir un arreglo JSON. Finalmente retornas Response(serializer.data), sin necesidad de especificar el estado porque 200 es el valor por defecto.

Cómo evitar que el formulario muestre los campos del doctor

Un detalle que aparece al probar el endpoint en la interfaz gráfica de Django REST es que el formulario de POST muestra los campos del doctor en lugar de los de la cita. Esto pasa porque el viewset infiere el serializer del recurso principal.

La solución es declarar serializer_class=AppointmentSerializer dentro del decorador @action. Con ese argumento, el browsable API renderiza los campos correctos: fecha, hora, notas, estado, paciente y doctor.

¿Por qué usar serializer_class dentro de @action? Porque la acción crea un recurso distinto al del viewset padre. Sin esa línea, la interfaz muestra los campos del doctor en vez de los de la cita.

Cómo probar el endpoint anidado en el navegador

Una vez levantado el servidor de desarrollo y autenticado, navegas al detalle de un doctor, por ejemplo /doctors/3/. En la barra superior aparecen las extra actions, incluida appointments.

Al entrar verás dos comportamientos:

Con GET obtienes la lista de citas filtradas por ese doctor.
Con POST se despliega el formulario para crear una cita nueva, donde defines fecha, hora, notas como urgente, estado en espera, y seleccionas el paciente. El doctor queda fijado por la URL.

Al enviar el POST, la respuesta devuelve el objeto creado con estado 201. Si recargas con GET, la nueva cita aparece en la lista junto a las anteriores.

Con esta estructura tienes un viewset anidado funcional que respeta REST, protege la relación con el doctor y aprovecha el ORM de Django para filtrar. ¿Te animas a extender la misma acción para borrar una cita por su id? Cuéntame en los comentarios cómo lo implementarías.

Ernesto Jose Gomez Flores

Hace un año

Yo lo tengo de forma diferente. En doctors puedo mediante un GET extraer un JSON con las citas medicas de un doctor especifico. PERO, en Patients puedo mediante un GET extraer un JSON de las citas que tiene un paciente especifico, y con un POST para añadir una cita medica del paciente con un doctor, con la condición de que el doctor no este de vacaciones.

Aca mi codigo:

Booking.serializers.py:

from rest_framework import serializers
from .models import Appointment, MedicalNote
from doctors.models import Doctor

class AppointmentSerializer(serializers.ModelSerializer):
    '''
    Serializer del modelo Appointment.
    Incluye todos los campos del modelo.
    * Atributos:
        - model: Modelo asociado (Appointment).
        - fields: Campos a incluir en la serialización (todos los campos).
    * Métodos:
        - Meta: Clase interna que define la configuración del serializer.
    '''
    
    # Asegura que solo se puedan asignar doctores que no estén de vacaciones.
    doctor = serializers.PrimaryKeyRelatedField(
        queryset=Doctor.objects.filter(is_on_vacation=False)
    )
    class Meta:
        model = Appointment
        fields = '__all__'
        
        read_only_fields = ['id', 'patient']

doctors.viewsets.py:

    @action(["GET"], detail=True, url_path="appointments")
    def get_appointments(self, request, pk) -> Response:
        '''
        Recupera las citas asociadas a un doctor específico.
        * Parámetros:
            - request: Objeto de solicitud HTTP.
            - pk: ID del doctor cuyas citas se van a recuperar.
        * Retorna:
            - Response: Objeto de respuesta HTTP con los datos de las citas del doctor.
        '''
        doctor = self.get_object()
        appointments = doctor.appointments.all()
        serializer = AppointmentSerializer(appointments, many=True)
        return Response(serializer.data)

en patients.serializers.py:

from rest_framework import serializers
from .models import Patient, Insurance, MedicalRecord
from bookings.serializers import AppointmentSerializer
from datetime import date

# Create your serializers here.
class PatientSerializer(serializers.ModelSerializer):
    '''
    Serializer del modelo Patient.
    Incluye todos los campos del modelo.
    * Atributos:
        - model: Modelo asociado (Patient).
        - fields: Campos a incluir en la serialización (todos los campos).
    * Métodos:
        - Meta: Clase interna que define la configuración del serializer.
    '''
    
    # Incluir detalles de las citas asociadas al historial médico.
    appointments = AppointmentSerializer(many=True, read_only=True)
    
    # Campo calculado para la edad del paciente.
    age = serializers.SerializerMethodField()

    class Meta:
        model = Patient
        fields = [
            'id',
            'first_name',
            'last_name',
            'age',
            'date_of_birth',
            'contact_number',
            'email',
            'address',
            'medical_history',
            'appointments'
        ]

y en patients.viewsets.py:

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 bookings.serializers import AppointmentSerializer
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
        if self.action == 'add_appointment':
            return AppointmentSerializer
        return super().get_serializer_class() # Retorna el serializador por defecto

    #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
        # Pasamos el contexto al serializador, lo cual es una buena práctica.
        # Aunque no se use ahora, es útil para futuras validaciones.
        serializer = self.get_serializer(data=request.data, context={'request': request})
        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)
    
    # Action personalizado para agregar una nueva cita al paciente
    @action(detail=True, methods=["post"], url_path="add-appointment")
    def add_appointment(self, request, pk) -> Response:
        '''
        Agrega una nueva cita a un paciente existente.
        * Parámetros:
            - request: Objeto de solicitud HTTP que contiene los datos de la cita.
            - pk: ID del paciente al que se le agregará la cita.
        * Retorna:
            - Response: Objeto de respuesta HTTP con la cita creada o errores de validación.
        '''
        patient = self.get_object()
        serializer = self.get_serializer(data=request.data, context={'request': request})
        serializer.is_valid(raise_exception=True)
        serializer.save(patient=patient)
        return Response(serializer.data, status=status.HTTP_201_CREATED)
    
    @action(["GET"], detail=True, url_path="appointments")
    def get_appointments(self, request, pk) -> Response:
        '''
        Recupera las citas asociadas a un paciente específico.
        * Parámetros:
            - request: Objeto de solicitud HTTP.
            - pk: ID del paciente cuyas citas se van a recuperar.
        * Retorna:
            - Response: Objeto de respuesta HTTP con los datos de las citas del paciente.
        '''
        patient = self.get_object()
        appointments = patient.appointments.all()
        serializer = AppointmentSerializer(appointments, many=True)
        return Response(serializer.data)

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

Endpoint anidado para citas en Django REST

Progreso del curso

Fundamentos de Django Rest Framework

Vistas y Endpoints

Serializadores Avanzados

Testing y Desempeño

Recursos

Recursos