8. El servidor RdvMedecins, una caja negra
Los ejemplos 22 a 25, seguidos del caso de estudio, interactúan con un servidor: el servidor JSON de la aplicación [RdvMedecins]. Es el servidor [NestJS] de los cursos [React], [Vue.js], [Angular] y [Flutter]: el servidor del curso de [NestJS], cuyos controladores ya no generan páginas HTML sino que producen respuestas JSON. Los lectores de estas lecciones ya conocen este capítulo, que se reproduce aquí casi sin cambios; solo necesitan consultar la sección sobre autenticación, que explica qué cambia para una aplicación [Ionic] instalada en un teléfono.
En este curso, este servidor es una caja negra: no necesita saber cómo está escrito. Lo único que importa es su API, es decir, la lista de solicitudes HTTP que acepta y las respuestas que devuelve. Esta es la situación típica de un desarrollador de clientes: la API es un contrato, y el equipo del servidor puede cambiar lo que quiera detrás de ese contrato. Su código fuente se proporciona (carpeta [rdvmedecins-nestjs-json]) y está ampliamente comentado, para el lector curioso.
Este capítulo explica cómo instalar el servidor, describe su API y lo consulta mediante [curl].
8.1. La aplicación RdvMedecins
La aplicación gestiona las citas de un consultorio médico. Tiene tres roles:
Rol | Quién | Qué puede hacer |
[ADMIN] | El administrador ([admin]) | Programar y cancelar citas de todos los pacientes; administrar médicos y clientes |
[DOCTOR] | Los médicos ([pelissier], [tatou], [dupont]) | Programar y cancelar citas de todos los pacientes; ver todos los nombres en los calendarios |
[USER] | Los pacientes ([martin], [durand], [bistrou], [german]) | reservar citas para sí mismos; cancelar sus citas; administrar sus cuentas. En un calendario, no pueden ver los nombres de los demás pacientes |
Las cuentas de demostración usan su login como contraseña. Las reglas de gestión las verifica el servidor, independientemente del cliente:
- no hay citas en el pasado;
- solo una cita futura por paciente;
- una franja horaria solo puede reservarse una vez por día;
- dos médicos (o dos clientes) no pueden tener el mismo nombre y apellido; un login pertenece a una sola cuenta;
- un médico con citas programadas no puede eliminarse;
- un registro que haya sido modificado entretanto por otra persona no puede sobrescribirse (bloqueo optimista);
- a un paciente nunca se le asigna el nombre de otro paciente.
8.2. Instalación
Se necesita [Node.js] (ya instalado para [Angular]; véase el Capítulo 2) y un servidor [MySQL] (o [MariaDB]): su instalación se describe en el apéndice.
1. La base de datos. El script [database/dbrdvmedecins2.sql] crea la base de datos [dbrdvmedecins2], sus tablas y sus datos de ejemplo. Con [Laragon], ejecútelo desde [HeidiSQL] (menú Archivo / Ejecutar un archivo SQL); en la línea de comandos:
| mysql -u root -p < database/dbrdvmedecins2.sql
|
El script siempre parte de una base de datos vacía: puede volver a ejecutarlo para restaurar los datos iniciales.
2. Bibliotecas. En una ventana de consola abierta en la carpeta [rdvmedecins-nestjs-json]:
3. Configuración. Copie el archivo [.env.example] a [.env] (en [Windows]: [copy .env.example .env]) y luego modifíquelo:
| # -----------------------------------------------------------------------
# Archivo de configuración de ejemplo.
# Copie este archivo a [.env] y luego adapte los valores a su máquina.
# El archivo [.env] nunca debe compartirse ni incluirse en un commit (contraseñas).
# -----------------------------------------------------------------------
# puerto de escucha del servidor JSON
PORT=8080
# parámetros de conexión a la base de datos MySQL [dbrdvmedecins2]
# (script: database/dbrdvmedecins2.sql)
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=dbrdvmedecins2
# true: muestra en la consola las consultas SQL enviadas a MySQL
DB_LOGGING=false
# -----------------------------------------------------------------------
# autenticación
# -----------------------------------------------------------------------
# clave secreta usada para firmar/verificar los tokens JWT - DEBE cambiarse
# en producción (una cadena larga aleatoria, nunca incluida en un commit).
JWT_SECRET=change-me-to-a-long-random-string
# validez de un token JWT, en segundos (7200 s = 2 h). La cookie
# que transporta el token tiene la misma duración.
JWT_EXPIRES_IN_SECONDS=7200
# poner en true en producción (sitio servido por HTTPS): la cookie de autenticación
# nunca se enviará entonces por una conexión sin cifrar.
COOKIE_SECURE=false
# -----------------------------------------------------------------------
# protección contra bots
# -----------------------------------------------------------------------
# login: número de fallos (captcha o contraseña incorrectos) permitidos para
# un mismo login desde la misma dirección IP, antes de bloquear este par...
LOGIN_MAX_FAILURES=5
# ... durante este tiempo (una dirección IP también se bloquea si acumula
# 5 veces más fallos, todos los logins combinados)
LOGIN_BLOCK_MINUTES=15
# creación de cuentas de clientes: número máximo de cuentas creadas por hora
# desde la misma dirección IP. En un salón de clases, todas las computadoras salen a menudo
# por la misma dirección: aumente el valor si es necesario.
REGISTRATION_MAX_PER_HOUR=10
# MODO DE PRUEBA del captcha: si esta variable tiene un valor, ese valor se
# acepta como respuesta a CUALQUIER captcha. Útil para consultar
# la API con curl (no se puede "leer" la imagen en una consola).
# Dejar VACÍO en producción.
CAPTCHA_TEST=
# -----------------------------------------------------------------------
# producción
# -----------------------------------------------------------------------
# carpeta del cliente web compilado, servida por este servidor (por defecto: client/)
# CLIENT_DIR=client
# poner en true si el servidor está detrás de un proxy (nginx...)
TRUST_PROXY=false
|
- línea 8: el servidor escucha en el puerto 8080;
- líneas 12–16: la conexión a [MySQL]. Con [Laragon], el usuario [root] no tiene contraseña: los valores predeterminados sirven;
- línea 25: la clave secreta que firma los tokens de autenticación;
- líneas 38–45: medidas antibots: después de 5 intentos fallidos de inicio de sesión para el mismo nombre de usuario desde la misma dirección IP (IP), esa combinación se bloquea durante 15 minutos; una misma dirección IP (IP) no puede crear más de 10 cuentas por hora. Durante el desarrollo de la aplicación —cuando los errores son frecuentes— puede encontrar estos valores en su archivo [.env];
- línea 51: el modo de prueba del CAPTCHA. La página de inicio de sesión le pide volver a escribir los caracteres de una imagen, lo cual es imposible desde una consola. Si esta variable tiene un valor, ese valor se acepta como respuesta a cualquier CAPTCHA, igual que las “claves de prueba” que [Google] ofrece para su [reCAPTCHA]. Para las pruebas con [curl] en este capítulo, ingrese [CAPTCHA_TEST=test]. Los scripts que generaron las capturas de pantalla de este curso también usan este valor. Déjelo vacío en producción;
- líneas 57–59: dos ajustes para producción (véase el capítulo “Despliegue”).
4. Inicio.
La consola muestra (extracto; [start:dev] reinicia el servidor cada vez que se modifica su código):
| [Nest] 13189 - 10/06/2026, 1:29:56 PM LOG [NestFactory] Starting Nest application...
[Nest] 13189 - 10/06/2026, 1:29:56 PM LOG [InstanceLoader] TypeOrmModule dependencies initialized +19ms
...
[Nest] 13189 - 10/06/2026, 1:29:56 PM WARN [RdvMedecins] captcha TEST MODE active (CAPTCHA_TEST in .env): never use it in production
[Nest] 13189 - 10/06/2026, 1:29:56 PM LOG [RoutesResolver] ScheduleController {/api/schedule}: +1ms
[Nest] 13189 - 10/06/2026, 1:29:56 PM LOG [RouterExplorer] Mapped {/api/schedule, GET} route +1ms
[Nest] 13189 - 10/06/2026, 1:29:56 PM LOG [RoutesResolver] AppointmentsController {/api/appointments}: +0ms
...
[Nest] 13189 - 10/06/2026, 1:29:56 PM LOG [RouterExplorer] Mapped {/api/auth/me, GET} route +0ms
[Nest] 13189 - 10/06/2026, 1:29:56 PM LOG [NestApplication] Nest application successfully started +6ms
[Nest] 13189 - 10/06/2026, 1:29:56 PM LOG [RdvMedecins] JSON server started: http://localhost:8080/api
|
Cada línea [Mapped] anuncia una ruta de la API. Si la base de datos es inaccesible (servidor [MySQL] detenido, contraseña incorrecta), el servidor se detiene de inmediato con un mensaje de error de conexión.
Todas las rutas comienzan con [/api]. Una solicitud exitosa recibe un código de estado 2xx y, en su cuerpo, los datos solicitados en formato JSON. Una solicitud rechazada recibe un código de estado 4xx o 5xx y, en el cuerpo, datos en el mismo formato:
| {
"statusCode": 400,
"key": "ERRORS.INVALID_FORM",
"params": { "min": "6" },
"fields": { "lastName": "ERRORS.LASTNAME_REQUIRED", "password": "ERRORS.PASSWORD_TOO_SHORT" }
}
|
- [statusCode]: el código HTTP, repetido en el cuerpo;
- [key]: la clave de traducción del mensaje. El servidor nunca devuelve texto para mostrar: no conoce el idioma del usuario. Es el cliente quien traduce la clave mediante sus diccionarios (véase el Ejemplo 21);
- [params] (opcional): parámetros del mensaje (“At least {{min}} characters”, “Please try again in {{minutes}} minute(s)”);
- [fields] (opcional): para un formulario rechazado, el error de cada campo.
Códigos utilizados:
Código | Significado | Ejemplos de claves |
400 | Solicitud no válida | [ERRORS.INVALID_FORM] (+ fields), [ERRORS.INVALID_DATE], [ERRORS.WRONG_CAPTCHA], [ERRORS.CHOOSE_PATIENT], [ERRORS.WRONG_CURRENT_PASSWORD], [ERRORS.BAD_REQUEST]... |
401 | no autenticado | [ERRORS.AUTH_REQUIRED] (sin token), [ERRORS.SESSION_EXPIRED] (token no válido o vencido), [LOGIN.ERROR] |
403 | Acceso denegado | [ERRORS.FORBIDDEN] (rol insuficiente), [ERRORS.CAPTCHA_BEFORE_ACCOUNT] (sin pase) |
404 | No encontrado | [ERRORS.NOT_FOUND], [ERRORS.DOCTOR_NOT_FOUND], [ERRORS.APPOINTMENT_NOT_FOUND]... |
409 | Violación de una regla de negocio | [ERRORS.PAST_DATE], [ERRORS.SLOT_ALREADY_BOOKED], [ERRORS.LOGIN_TAKEN], [ERRORS.CONCURRENT_UPDATE]... |
415 | POST que no es JSON | [ERRORS.JSON_REQUIRED] |
429 | Demasiados intentos | [ERRORS.TOO_MANY_ATTEMPTS], [ERRORS.TOO_MANY_ACCOUNTS] (+ params.minutes) |
500 | error del servidor | [ERRORS.SERVER_ERROR] |
8.4. Autenticación
El cliente se autentica mediante [POST /api/auth/login], con un nombre de usuario, una contraseña y una respuesta al CAPTCHA. A cambio, el servidor envía, en el encabezado [Set-Cookie] de su respuesta, una cookie que contiene un token JWT firmado:
| Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; Expires=Tue, 06 Oct 2026 14:12:15 GMT; HttpOnly; SameSite=Strict
|
A partir de entonces, el cliente debe incluir esta cookie en el encabezado [Cookie] de cada solicitud a [/api]: así es como el servidor sabe quién hace la solicitud.
Este servidor fue diseñado para clientes web, y sus decisiones de diseño responden a los riesgos propios de los navegadores web:
- [HttpOnly]: el código [JavaScript] de la página no puede leer esta cookie. Un script malicioso inyectado en la página no podría, por lo tanto, robar el token. Consecuencia para el cliente: no puede determinar por sí mismo si ha iniciado sesión. Se lo pregunta al servidor ([GET /api/auth/me]);
- [Path=/api]: la cookie solo se incluye en las solicitudes a la API;
- [SameSite=Strict]: el navegador solo incluye la cookie en las solicitudes enviadas desde una página de este sitio. Una página maliciosa de otro sitio no puede hacer que el navegador actúe en nombre del usuario (un ataque llamado CSRF);
- [Max-Age=7200]: vence después de dos horas, al mismo tiempo que vence el token.
Una segunda salvaguarda contra los ataques CSRF: el servidor rechaza (415) cualquier solicitud POST cuyo cuerpo no esté en JSON. Un formulario HTML comprometido en otro sitio no puede enviar JSON.
8.4.1. Qué cambia para un cliente móvil
Una aplicación [Ionic] es una aplicación web ejecutada en el teléfono por un “WebView” (el motor de navegador [Chrome] de [Android]): ¿sigue las mismas reglas que un navegador? En este curso, debemos distinguir entre las dos formas en que se ejecuta.
En el navegador de la computadora, durante el desarrollo ([ng serve]). La aplicación la sirve el servidor de desarrollo de [Angular] (http://localhost:8100); el servidor JSON está en un puerto distinto (8080). Son dos orígenes distintos, y el navegador aplicaría dos reglas problemáticas: no aceptaría respuestas de un origen distinto a menos que el servidor lo autorice (el mecanismo “CORS”, que nuestro servidor no admite), y no incluiría la cookie [SameSite=Strict] en las solicitudes “desde otro sitio”. La solución es la misma que en los cursos de [React] y [Vue.js]: un proxy. El servidor de desarrollo reenvía al servidor JSON toda solicitud cuya dirección comience con [/api] (archivo [proxy.conf.json], véase el Ejemplo 22). Desde la perspectiva del navegador, la aplicación y la API comparten el mismo origen: el navegador almacena la cookie y la devuelve, y el código de la aplicación no necesita hacer nada.
En el teléfono ([Android], [Capacitor]). La página la sirve [Capacitor] mismo, desde la dirección https://localhost; el servidor JSON está en la computadora, en una dirección como http://10.0.2.2:8080 (véase el Ejemplo 22). Nuevamente, hay dos orígenes. El proyecto activa el plugin [CapacitorHttp] de [Capacitor] (archivo [capacitor.config.ts]): las solicitudes HTTP de la aplicación ya no las envía el WebView sino el código nativo de [Android]. Consecuencias:
- ya no hay verificación CORS: esta verificación es una regla del navegador, y el código nativo no es un navegador (ni lo es [curl]);
- las cookies recibidas las almacena [Android] (su administrador de cookies, el mismo que el del WebView) y se reenvían automáticamente con las solicitudes posteriores al mismo servidor. Se conservan en el dispositivo: la sesión permanece iniciada cuando se cierra y se vuelve a abrir la aplicación;
- los atributos [HttpOnly] y [SameSite] no causan ningún problema: el código de la aplicación nunca lee la cookie (pregunta con [GET /api/auth/me] quién ha iniciado sesión), y la solicitud no la envía una página “de otro sitio”.
Esta es una diferencia importante con el curso de [Flutter]: una aplicación [Flutter] no tiene navegador, y tuvo que escribir su propio cliente HTTP que lee el encabezado [Set-Cookie] de las respuestas y escribe el encabezado [Cookie] en las solicitudes. Con [Ionic], tanto en el navegador como en el teléfono, la cookie se transmite sin una sola línea de código. El servidor, por su parte, no necesita cambiar nada: solo ve solicitudes HTTP normales, que incluyen la cookie que él estableció.
8.5. La API
Método | Dirección | Roles | Cuerpo enviado/respuesta |
GET | [/api/captcha] | público | Respuesta: [{ id, svg }] |
POST | [/api/auth/login] | público | [{ login, password, captchaId, captcha }]; respuesta: [{ login, name, role }] + cookie |
POST | [/api/auth/logout] | público | [{}] ; elimina la cookie |
GET | [/api/auth/me] | con sesión iniciada | respuesta: [{ login, name, role }] |
GET | [/api/schedule?doctorId=&day=] | todos | Respuesta: el calendario (sin doctorId: para un DOCTOR, el suyo propio) |
POST | [/api/appointments] | todos | [{ day, slotId, clientId }] (clientId se ignora para un USER); 201 |
DELETE | [/api/appointments/:id] | todos | Un USER solo cancela las suyas |
GET | [/api/doctors] | todos | la lista (con login para ADMIN) |
GET | [/api/clients] | ADMIN, DOCTOR | la lista (con login para ADMIN) |
GET | [/api/doctors/:id], [/api/clients/:id] | ADMIN | un registro |
POST | [/api/doctors], [/api/clients] | ADMIN | [{ title, firstName, lastName, login?, password? }]; 201 |
PUT | [/api/doctors/:id], [/api/clients/:id] | ADMIN | [{ title, firstName, lastName, login?, password?, version }] |
DELETE | [/api/doctors/:id], [/api/clients/:id] | ADMIN | Respuesta: [{}] |
POST | [/api/register/access] | público | [{ captchaId, captcha }]; emite un token (cookie) |
GET | [/api/register/access] | público | respuesta: [{ valid }] |
POST | [/api/register] | público + pase | [{ title, firstName, lastName, login, password, confirmation }]; 201 |
GET | [/api/my-area] | USER | Respuesta: [{ patient, appointments }] |
GET | [/api/my-account] | USER | Respuesta: [{ title, firstName, lastName, login, version }] |
PUT | [/api/my-account] | USER | [{ title, firstName, lastName, login, password?, confirmation?, currentPassword, version }] |
DELETE | [/api/my-account] | USER | [{ currentPassword }]; elimina la cuenta y sus citas |
Una entrada del calendario ([GET /api/schedule]) describe una franja horaria Y lo que el usuario con sesión iniciada está autorizado a hacer con ella:
| { "id": 3, "startHour": 8, "startMinute": 40, "endHour": 9, "endMinute": 0,
"free": false,
"patient": { "title": "Mme", "firstName": "Alice", "lastName": "DURAND" },
"mine": false, "bookable": false, "appointmentId": 2 }
|
- [free]: ¿está disponible la franja horaria ese día?
- [patient]: el paciente de la cita. Para un paciente con sesión iniciada, es igual a [null], salvo en el caso de SU PROPIA cita: los nombres de los demás pacientes nunca se envían;
- [mine]: es la cita del paciente con sesión iniciada;
- [bookable]: ¿puede el usuario reservar esta franja horaria (disponible, no en el pasado y, para un paciente, sin citas futuras)?
- [appointmentId]: se completa si el usuario puede cancelar esta cita.
El servidor DECIDE; el cliente muestra. E incluso si un cliente hiciera trampa (mostrando un botón “Reservar” cuando no debería), el servidor volvería a verificar todo en el momento de la reserva.
8.6. Consultar la API con curl
La carpeta [curl] del servidor contiene los cuerpos JSON de las solicitudes de este capítulo, un archivo por solicitud. Por ejemplo, [curl/login-admin.json]:
| { "login": "admin", "password": "admin", "captchaId": "-", "captcha": "test" }
|
Los comandos se ingresan en una consola abierta en el directorio [rdvmedecins-nestjs-json], con el servidor en ejecución en modo de prueba del CAPTCHA ([CAPTCHA_TEST=test]) sobre una base de datos recién (re)inicializada. Algunas opciones de [curl]:
- [-i]: muestra también los encabezados de la respuesta; [-s]: sin barra de progreso;
- [--json @file]: envía el contenido del archivo mediante POST, con el encabezado [Content-Type: application/json] ([curl] 7.82 y posteriores; con una versión anterior, use [-H "Content-Type: application/json" -d @file]);
- [-X PUT], [-X DELETE]: el método HTTP;
- [-c cookies.txt]: guarda las cookies recibidas en este archivo; [-b cookies.txt]: las reenvía. Así es como [curl] “mantiene la sesión iniciada” de un comando al siguiente, igual que lo haría un navegador.
En [PowerShell], debe ingresar [curl.exe] y no [curl] (que se refiere a otro comando). La siguiente salida proviene de una sesión real (6 de octubre de 2026, con citas programadas para enero de 2030, de modo que sigan estando en el futuro). Las respuestas JSON, algo extensas, se han formateado para este documento (una línea por objeto), mientras que los tokens JWT y la imagen del CAPTCHA se han truncado (“... ”), y se han eliminado los encabezados [Date], [ETag], [Connection] y [Keep-Alive].
8.6.1. Inicio de sesión
Primero, el CAPTCHA (la imagen está truncada):
| $ curl -i http://localhost:8080/api/captcha
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json; charset=utf-8
Content-Length: 13195
{"id":"8f711d55-566c-44e6-b02b-f114a02279f6","svg":"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"150..."}
|
Sin un token, una URL protegida devuelve una respuesta 401:
| $ curl -i http://localhost:8080/api/doctors
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 47
{"statusCode":401,"key":"ERRORS.AUTH_REQUIRED"}
|
Un CAPTCHA incorrecto, seguido de una contraseña incorrecta:
| $ curl -i --json @curl/login-wrong-captcha.json http://localhost:8080/api/auth/login
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 91
{"statusCode":400,"key":"ERRORS.WRONG_CAPTCHA","fields":{"captcha":"ERRORS.WRONG_CAPTCHA"}}
|
| $ curl -i --json @curl/login-wrong-password.json http://localhost:8080/api/auth/login
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 38
{"statusCode":401,"key":"LOGIN.ERROR"}
|
Un inicio de sesión exitoso establece la cookie, que [curl] almacena en [cookies.txt]:
| $ curl -i -c cookies.txt --json @curl/login-admin.json http://localhost:8080/api/auth/login
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; Expires=Tue, 06 Oct 2026 14:12:15 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 55
{"login":"admin","name":"Administrator","role":"ADMIN"}
|
Con esta cookie, el servidor sabe quiénes somos:
| $ curl -i -b cookies.txt http://localhost:8080/api/auth/me
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 55
{"login":"admin","name":"Administrator","role":"ADMIN"}
|
Un token falsificado (o vencido) produce una sesión vencida, y el servidor solicita que se elimine la cookie (una fecha de vencimiento ya pasada):
| $ curl -i -b "rdvmedecins_jwt=abc.def.ghi" http://localhost:8080/api/auth/me
HTTP/1.1 401 Unauthorized
Set-Cookie: rdvmedecins_jwt=; Path=/api; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 49
{"statusCode":401,"key":"ERRORS.SESSION_EXPIRED"}
|
8.6.2. Médicos, clientes, calendario
La lista de médicos, vista por ADMIN (con los logins):
| $ curl -i -b cookies.txt http://localhost:8080/api/doctors
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 282
[
{"id":3,"version":0,"title":"Melle","firstName":"Sophie","lastName":"DUPONT","login":"dupont"},
{"id":1,"version":0,"title":"Mme","firstName":"Marie","lastName":"PELISSIER","login":"pelissier"},
{"id":2,"version":0,"title":"Mr","firstName":"Paul","lastName":"TATOU","login":"tatou"}
]
|
El calendario del Dr. PELISSIER para el 15 de enero de 2030:
| $ curl -s -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
"doctor":{"id":1,"version":0,"title":"Mme","firstName":"Marie","lastName":"PELISSIER"},
"day":"2030-01-15",
"slots":[
{"id":1,"startHour":8,"startMinute":0,"endHour":8,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":2,"startHour":8,"startMinute":20,"endHour":8,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":3,"startHour":8,"startMinute":40,"endHour":9,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":4,"startHour":9,"startMinute":0,"endHour":9,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":5,"startHour":9,"startMinute":20,"endHour":9,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":6,"startHour":9,"startMinute":40,"endHour":10,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":7,"startHour":10,"startMinute":0,"endHour":10,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":8,"startHour":10,"startMinute":20,"endHour":10,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":9,"startHour":10,"startMinute":40,"endHour":11,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":10,"startHour":11,"startMinute":0,"endHour":11,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":11,"startHour":11,"startMinute":20,"endHour":11,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":12,"startHour":11,"startMinute":40,"endHour":12,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null}
],
"info":null
}
|
Una fecha que no existe:
| $ curl -i -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-02-30"
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 46
{"statusCode":400,"key":"ERRORS.INVALID_DATE"}
|
8.6.3. Citas
ADMIN reserva la franja 3 para el paciente n.º 2 (Alice DURAND). El cuerpo de la solicitud ([curl/appointment-admin.json]):
| { "day": "2030-01-15", "slotId": 3, "clientId": 2 }
|
| $ curl -i -b cookies.txt --json @curl/appointment-admin.json http://localhost:8080/api/appointments
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 51
{"id":2,"day":"2030-01-15","slotId":3,"clientId":2}
|
El calendario muestra ahora esta cita, junto con el nombre del paciente y las instrucciones para cancelarla ([appointmentId]):
| $ curl -s -b cookies.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
"doctor":{"id":1,"version":0,"title":"Mme","firstName":"Marie","lastName":"PELISSIER"},
"day":"2030-01-15",
"slots":[
{"id":1,"startHour":8,"startMinute":0,"endHour":8,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":2,"startHour":8,"startMinute":20,"endHour":8,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":3,"startHour":8,"startMinute":40,"endHour":9,"endMinute":0,"free":false,"patient":{"title":"Mme","firstName":"Alice","lastName":"DURAND"},"mine":false,"bookable":false,"appointmentId":2},
{"id":4,"startHour":9,"startMinute":0,"endHour":9,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":5,"startHour":9,"startMinute":20,"endHour":9,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":6,"startHour":9,"startMinute":40,"endHour":10,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":7,"startHour":10,"startMinute":0,"endHour":10,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":8,"startHour":10,"startMinute":20,"endHour":10,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":9,"startHour":10,"startMinute":40,"endHour":11,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":10,"startHour":11,"startMinute":0,"endHour":11,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":11,"startHour":11,"startMinute":20,"endHour":11,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":12,"startHour":11,"startMinute":40,"endHour":12,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null}
],
"info":null
}
|
Intentemos de nuevo: el paciente ya tiene una cita futura. Una cita en el pasado (15 de enero de 2020, archivo [curl/appointment-past.json]) también es rechazada:
| $ curl -i -b cookies.txt --json @curl/appointment-admin.json http://localhost:8080/api/appointments
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 66
{"statusCode":409,"key":"ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT"}
|
| $ curl -i -b cookies.txt --json @curl/appointment-past.json http://localhost:8080/api/appointments
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 43
{"statusCode":409,"key":"ERRORS.PAST_DATE"}
|
Un formulario HTML estándar (simulado aquí mediante [-d], que envía [application/x-www-form-urlencoded]) es rechazado:
| $ curl -i -b cookies.txt -d "day=2030-01-15&slotId=4&clientId=2" http://localhost:8080/api/appointments
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json; charset=utf-8
Content-Length: 47
{"statusCode":415,"key":"ERRORS.JSON_REQUIRED"}
|
8.6.4. La perspectiva de un paciente
Cerramos sesión y luego iniciamos sesión como [martin]:
| $ curl -i -b cookies.txt -c cookies.txt --json @curl/empty.json http://localhost:8080/api/auth/logout
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=; Path=/api; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
| $ curl -s -c cookies-martin.txt --json @curl/login-martin.json http://localhost:8080/api/auth/login
{"login":"martin","name":"Jean MARTIN","role":"USER"}
|
La misma agenda, vista por un paciente: la franja 3 está ocupada (["free":false]), pero ["patient"] equivale a [null]: el nombre de Alice (DURAND) no se envió:
| $ curl -s -b cookies-martin.txt "http://localhost:8080/api/schedule?doctorId=1&day=2030-01-15"
{
"doctor":{"id":1,"version":0,"title":"Mme","firstName":"Marie","lastName":"PELISSIER"},
"day":"2030-01-15",
"slots":[
{"id":1,"startHour":8,"startMinute":0,"endHour":8,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":2,"startHour":8,"startMinute":20,"endHour":8,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":3,"startHour":8,"startMinute":40,"endHour":9,"endMinute":0,"free":false,"patient":null,"mine":false,"bookable":false,"appointmentId":null},
{"id":4,"startHour":9,"startMinute":0,"endHour":9,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":5,"startHour":9,"startMinute":20,"endHour":9,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":6,"startHour":9,"startMinute":40,"endHour":10,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":7,"startHour":10,"startMinute":0,"endHour":10,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":8,"startHour":10,"startMinute":20,"endHour":10,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":9,"startHour":10,"startMinute":40,"endHour":11,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":10,"startHour":11,"startMinute":0,"endHour":11,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":11,"startHour":11,"startMinute":20,"endHour":11,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":12,"startHour":11,"startMinute":40,"endHour":12,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null}
],
"info":null
}
|
Un paciente no tiene acceso a la lista de clientes:
| $ curl -i -b cookies-martin.txt http://localhost:8080/api/clients
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 43
{"statusCode":403,"key":"ERRORS.FORBIDDEN"}
|
Reserva para sí mismo (el registro, [curl/appointment-martin.json], no contiene [clientId]), una vez, no dos ([curl/appointment-martin-2.json]: el día siguiente, franja 6):
| { "day": "2030-01-15", "slotId": 5 }
|
| $ curl -i -b cookies-martin.txt --json @curl/appointment-martin.json http://localhost:8080/api/appointments
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 51
{"id":3,"day":"2030-01-15","slotId":5,"clientId":1}
|
| $ curl -i -b cookies-martin.txt --json @curl/appointment-martin-2.json http://localhost:8080/api/appointments
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 55
{"statusCode":409,"key":"SCHEDULE.ALREADY_BOOKED_INFO"}
|
Su área:
| $ curl -s -b cookies-martin.txt http://localhost:8080/api/my-area
{
"patient":{"title":"Mr","firstName":"Jean","lastName":"MARTIN"},
"appointments":[
{
"id":3,
"day":"2030-01-15",
"slot":{"id":5,"startHour":9,"startMinute":20,"endHour":9,"endMinute":40},
"doctor":{"id":1,"version":0,"title":"Mme","firstName":"Marie","lastName":"PELISSIER"}
}
]
}
|
No puede cancelar la cita de otro paciente. El servidor responde “no encontrado”, igual que lo haría con una cita que no existe: no revela nada sobre las citas de otros pacientes:
| $ curl -i -b cookies-martin.txt -X DELETE http://localhost:8080/api/appointments/2
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 55
{"statusCode":404,"key":"ERRORS.APPOINTMENT_NOT_FOUND"}
|
La suya, sí:
| $ curl -i -b cookies-martin.txt -X DELETE http://localhost:8080/api/appointments/3
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
8.6.5. La perspectiva de un médico
El Dr. PELISSIER inicia sesión:
| $ curl -s -c cookies-pelissier.txt --json @curl/login-pelissier.json http://localhost:8080/api/auth/login
{"login":"pelissier","name":"Marie PELISSIER","role":"DOCTOR"}
|
Sin [doctorId], un médico con sesión iniciada recibe SU PROPIA agenda, con todos los nombres (la cita de [martin] acaba de cancelarse: la cita de Alice, DURAND, permanece):
| $ curl -s -b cookies-pelissier.txt "http://localhost:8080/api/schedule?day=2030-01-15"
{
"doctor":{"id":1,"version":0,"title":"Mme","firstName":"Marie","lastName":"PELISSIER"},
"day":"2030-01-15",
"slots":[
{"id":1,"startHour":8,"startMinute":0,"endHour":8,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":2,"startHour":8,"startMinute":20,"endHour":8,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":3,"startHour":8,"startMinute":40,"endHour":9,"endMinute":0,"free":false,"patient":{"title":"Mme","firstName":"Alice","lastName":"DURAND"},"mine":false,"bookable":false,"appointmentId":2},
{"id":4,"startHour":9,"startMinute":0,"endHour":9,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":5,"startHour":9,"startMinute":20,"endHour":9,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":6,"startHour":9,"startMinute":40,"endHour":10,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":7,"startHour":10,"startMinute":0,"endHour":10,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":8,"startHour":10,"startMinute":20,"endHour":10,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":9,"startHour":10,"startMinute":40,"endHour":11,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":10,"startHour":11,"startMinute":0,"endHour":11,"endMinute":20,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":11,"startHour":11,"startMinute":20,"endHour":11,"endMinute":40,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null},
{"id":12,"startHour":11,"startMinute":40,"endHour":12,"endMinute":0,"free":true,"patient":null,"mine":false,"bookable":true,"appointmentId":null}
],
"info":null
}
|
No administra médicos:
| $ curl -i -b cookies-pelissier.txt --json @curl/doctor-add.json http://localhost:8080/api/doctors
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 43
{"statusCode":403,"key":"ERRORS.FORBIDDEN"}
|
8.6.6. Administración de médicos y clientes (ADMIN)
ADMIN vuelve a iniciar sesión (se había desconectado antes):
| $ curl -s -c cookies.txt --json @curl/login-admin.json http://localhost:8080/api/auth/login
{"login":"admin","name":"Administrator","role":"ADMIN"}
|
Una adición. Si falta el nombre de usuario, el valor predeterminado es el nombre en minúsculas; la contraseña es el nombre de usuario ([curl/doctor-add.json]):
| { "title": "Mme", "firstName": "Claire", "lastName": "LEROY" }
|
| $ curl -i -b cookies.txt --json @curl/doctor-add.json http://localhost:8080/api/doctors
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Content-Length: 90
{"id":4,"version":1,"title":"Mme","firstName":"Claire","lastName":"LEROY","login":"leroy"}
|
Cuerpo no válido: la respuesta enumera el error de cada campo ([curl/doctor-invalid.json]):
| { "title": "Dr", "firstName": "", "lastName": "A-LAST-NAME-FAR-TOO-LONG-FOR-THE-DB", "login": "Claire L" }
|
| $ curl -i -b cookies.txt --json @curl/doctor-invalid.json http://localhost:8080/api/doctors
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 218
{
"statusCode":400,
"key":"ERRORS.INVALID_FORM",
"params":{"min":"6"},
"fields":{"login":"ERRORS.INVALID_LOGIN","title":"ERRORS.INVALID_TITLE","firstName":"ERRORS.FIRSTNAME_REQUIRED","lastName":"ERRORS.LASTNAME_TOO_LONG"}
}
|
Un homónimo (el Sr. Paul TATOU, [curl/doctor-duplicate.json]): se señalan los dos campos afectados:
| $ curl -i -b cookies.txt --json @curl/doctor-duplicate.json http://localhost:8080/api/doctors
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 151
{
"statusCode":409,
"key":"ERRORS.DOCTOR_ALREADY_EXISTS",
"fields":{"firstName":"ERRORS.DOCTOR_ALREADY_EXISTS","lastName":"ERRORS.DOCTOR_ALREADY_EXISTS"}
}
|
Una modificación. [version] es la que se leyó junto con el registro (aquí 1, [curl/doctor-edit.json]):
| { "title": "Mme", "firstName": "Claire", "lastName": "LEROY-MARTIN", "version": 1 }
|
| $ curl -i -b cookies.txt -X PUT --json @curl/doctor-edit.json http://localhost:8080/api/doctors/4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 97
{"id":4,"version":2,"title":"Mme","firstName":"Claire","lastName":"LEROY-MARTIN","login":"leroy"}
|
El registro está ahora en la versión 2. Volver a enviar el mismo cambio (con la versión 1) sobrescribiría un registro que ha sido modificado entretanto por otra persona: esto es lo que impide el bloqueo optimista:
| $ curl -i -b cookies.txt -X PUT --json @curl/doctor-edit.json http://localhost:8080/api/doctors/4
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 51
{"statusCode":409,"key":"ERRORS.CONCURRENT_UPDATE"}
|
Un médico con citas no puede eliminarse; los demás sí:
| $ curl -i -b cookies.txt -X DELETE http://localhost:8080/api/doctors/1
HTTP/1.1 409 Conflict
Content-Type: application/json; charset=utf-8
Content-Length: 57
{"statusCode":409,"key":"ERRORS.DOCTOR_HAS_APPOINTMENTS"}
|
| $ curl -i -b cookies.txt -X DELETE http://localhost:8080/api/doctors/4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
8.6.7. Creación de una cuenta
Sin un pase, es imposible:
| $ curl -i --json @curl/registration.json http://localhost:8080/api/register
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 56
{"statusCode":403,"key":"ERRORS.CAPTCHA_BEFORE_ACCOUNT"}
|
Primero, se resuelve un CAPTCHA ([curl/captcha-test.json]: [{ "captchaId": "-", "captcha": "test" }]); el servidor emite un token, válido durante 15 minutos, en una cookie:
| $ curl -i -c cookies-registration.txt --json @curl/captcha-test.json http://localhost:8080/api/register/access
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_registration=d2f6290a-b277-4785-9fd9-fada3be36087; Max-Age=900; Path=/api/register; Expires=Tue, 06 Oct 2026 12:27:16 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
| $ curl -s -b cookies-registration.txt http://localhost:8080/api/register/access
{"valid":true}
|
La confirmación de la contraseña debe ser idéntica ([curl/registration-confirmation.json]: “secret1”, luego “secret2”):
| $ curl -i -b cookies-registration.txt --json @curl/registration-confirmation.json http://localhost:8080/api/register
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 98
{"statusCode":400,"key":"ERRORS.INVALID_FORM","fields":{"confirmation":"ERRORS.PASSWORDS_DIFFER"}}
|
El cuerpo correcto ([curl/registration.json]):
| { "title": "Mme", "firstName": "Julie", "lastName": "BERNARD", "login": "jbernard", "password": "secret1", "confirmation": "secret1" }
|
| $ curl -i -b cookies-registration.txt -c cookies-registration.txt --json @curl/registration.json http://localhost:8080/api/register
HTTP/1.1 201 Created
Set-Cookie: rdvmedecins_registration=; Path=/api/register; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 20
{"login":"jbernard"}
|
El pase ya se ha usado: no puede utilizarse para crear una segunda cuenta:
| $ curl -i -b cookies-registration.txt --json @curl/registration.json http://localhost:8080/api/register
HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Content-Length: 56
{"statusCode":403,"key":"ERRORS.CAPTCHA_BEFORE_ACCOUNT"}
|
8.6.8. Administrar su cuenta
La nueva paciente inicia sesión y lee su registro:
| $ curl -s -c cookies-jbernard.txt --json @curl/login-jbernard.json http://localhost:8080/api/auth/login
{"login":"jbernard","name":"Julie BERNARD","role":"USER"}
|
| $ curl -s -b cookies-jbernard.txt http://localhost:8080/api/my-account
{"title":"Mme","firstName":"Julie","lastName":"BERNARD","login":"jbernard","version":1}
|
Un cambio requiere la contraseña actual. El servidor emite un nuevo token, que contiene el nuevo nombre ([curl/my-account.json]):
| { "title": "Mme", "firstName": "Julie", "lastName": "BERNARD-DUVAL", "login": "jbernard", "currentPassword": "secret1", "version": 1 }
|
| $ curl -i -b cookies-jbernard.txt -c cookies-jbernard.txt -X PUT --json @curl/my-account.json http://localhost:8080/api/my-account
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=eyJhbGciOiJIUzI1NiIs...; Max-Age=7200; Path=/api; Expires=Tue, 06 Oct 2026 14:12:17 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json; charset=utf-8
Content-Length: 63
{"login":"jbernard","name":"Julie BERNARD-DUVAL","role":"USER"}
|
La eliminación de la cuenta ([curl/my-account-delete.json]: [{ "currentPassword": "secret1" }]) también elimina la cookie:
| $ curl -i -b cookies-jbernard.txt -c cookies-jbernard.txt -X DELETE --json @curl/my-account-delete.json http://localhost:8080/api/my-account
HTTP/1.1 200 OK
Set-Cookie: rdvmedecins_jwt=; Path=/api; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
|
| $ curl -i -b cookies-jbernard.txt http://localhost:8080/api/auth/me
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 47
{"statusCode":401,"key":"ERRORS.AUTH_REQUIRED"}
|
8.6.9. Algunos errores
Una ruta desconocida, un cuerpo que no es un JSON válido:
| $ curl -i -b cookies-martin.txt http://localhost:8080/api/does-not-exist
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 43
{"statusCode":404,"key":"ERRORS.NOT_FOUND"}
|
| $ curl -i -b cookies.txt -H "Content-Type: application/json" -d "{not json" http://localhost:8080/api/appointments
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 45
{"statusCode":400,"key":"ERRORS.BAD_REQUEST"}
|
Ya sabemos todo lo que necesitamos saber sobre el servidor para escribir nuestro cliente.