Skip to content

9. Comunicación con el servidor

El servidor JSON de [RdvMedecins] debe iniciarse ahora (puerto 8080), como se explicó en el capítulo anterior, preferiblemente en modo de prueba del CAPTCHA ([CAPTCHA_TEST=test]), que permite responder “test” a cualquier imagen.

Los ejemplos 22 a 25 comparten algunos archivos, ubicados en la carpeta [src/app/common/] del proyecto: la dirección del servidor ([config.ts]), los tipos de respuesta ([types.ts]), las clases de error ([api-error.ts]), el servicio de solicitudes ([api.ts]) y una barra de inicio de sesión ([login-bar.ts]). Se presentan a lo largo de los ejemplos a medida que resultan pertinentes.

9.1. Ejemplo 22: una primera solicitud HTTP

9.1.1. ¿Dónde está el servidor?

Para un cliente web servido por el propio servidor, la pregunta no se plantea: las solicitudes se envían al mismo origen que la página, mediante una dirección relativa ([/api/captcha]). Una aplicación instalada en un teléfono no tiene un origen utilizable: su página la sirve [Capacitor] mismo, desde https://localhost. Hay que proporcionar la dirección completa del servidor, y esta dirección depende de dónde se ejecute la aplicación:

// =========================================================================
// src/app/common/config.ts - ¿DÓNDE está el servidor JSON?
// -------------------------------------------------------------------------
// La pregunta no se plantea para una aplicación web servida por el
// propio servidor: las solicitudes van al MISMO origen que la página
// (una dirección relativa, /api/...). Pero una aplicación MÓVIL no tiene un
// origen utilizable (en Android, la página es servida por Capacitor
// desde https://localhost): hay que darle la dirección completa del servidor.
//   - en desarrollo web (ng serve), el servidor de desarrollo de Angular
//     reenvía las solicitudes /api al servidor JSON (archivo
//     proxy.conf.json): basta una dirección relativa;
//   - el emulador de Android ve la computadora que lo ejecuta en
//     la dirección 10.0.2.2 (localhost, para él, es el propio emulador);
//   - un teléfono real, conectado a la misma red Wi-Fi que la computadora, debe
//     usar la dirección de la computadora en esta red (192.168.1.20...):
//     se proporciona al compilar la aplicación:
//         ng build --define "SERVER='http://192.168.1.20:8080'"
//     o bien se cambia la constante androidServer de más abajo.
// =========================================================================

import { Capacitor } from '@capacitor/core';

// la dirección del servidor para la aplicación Android, cuando no se impone nada más:
// la de la computadora, vista desde el emulador
const androidServer = 'http://10.0.2.2:8080';

// el valor dado por --define "SERVER='...'" en el momento de la compilación
// (ng build, ng serve). La opción reemplaza, en el código compilado, la palabra
// SERVER por el valor dado. Sin ella, SERVER no existe: typeof
// permite comprobarlo sin provocar un error
declare const SERVER: string | undefined;
const forcedServer = typeof SERVER === 'string' ? SERVER : '';

export const config = {
  // Capacitor.isNativePlatform(): true en la aplicación Android (o iOS),
  // false en un navegador; Capacitor.getPlatform(): 'android', 'ios' o 'web'
  serverUrl:
    forcedServer !== ''
      ? forcedServer
      : !Capacitor.isNativePlatform()
        ? '' // la web: mismo origen, direcciones relativas
        : Capacitor.getPlatform() === 'android'
          ? androidServer
          : 'http://localhost:8080',
};
  • línea 21: [Capacitor], el objeto de [@capacitor/core] que proporciona información sobre la plataforma en la que se ejecuta la aplicación. Se puede usar en cualquier lugar, incluso en un navegador;
  • línea 25: la dirección predeterminada es la de [Android]. El emulador es una máquina independiente con su propia red: para el emulador, [localhost] se refiere al propio emulador. La dirección especial [10.0.2.2] se refiere a la computadora que lo ejecuta;
  • líneas 31–32: una dirección impuesta durante la compilación de la aplicación mediante la opción [--define] de [Angular]: [ng build --define "SERVER='http://192.168.1.20:8080'"]. La compilación reemplaza el identificador [SERVER] en el código por el valor dado (una cadena, de ahí los apóstrofes). Sin esta opción, [SERVER] no existe: [declare const] informa al compilador de [TypeScript] que [SERVER] es un identificador cuya declaración no ve, y [typeof SERVER] permite comprobar su existencia sin causar un error. Es el equivalente exacto de [--dart-define] y [String.fromEnvironment] en [Flutter];
  • líneas 34–45: de lo contrario, una dirección específica de la plataforma. [Capacitor.isNativePlatform()] es verdadero en la aplicación [Android] (o [iOS]), pero falso en un navegador; [Capacitor.getPlatform()] devuelve 'android', 'ios' o 'web':
  • en el navegador (línea 41): una URL relativa (''), es decir, el mismo origen que la aplicación;
  • en [Android] (línea 43): la dirección de la línea 25;
  • en cualquier otro caso (línea 44, [iOS], que este curso no cubre): [localhost].

Un teléfono real, conectado a la misma red Wi-Fi que la computadora del servidor, debe usar la dirección de la computadora en esa red (el comando [ipconfig] de [Windows] la proporciona): puede pasarla mediante [--define] durante la compilación, o modificar la constante de la línea 25. El firewall de la computadora también debe permitir las conexiones entrantes en el puerto 8080.

9.1.2. Configuración del proyecto Android

El cliente [Flutter] modificaba dos líneas del archivo [android/app/src/main/AndroidManifest.xml]: el permiso para usar la red y la autorización para comunicarse en HTTP sin cifrar (“texto plano”). Con [Capacitor], este archivo no se modifica:

  • el permiso [android.permission.INTERNET] ya está declarado en el proyecto [Android] creado por [npx cap add android]: una aplicación [Capacitor] es una página web, por lo que siempre requiere acceso a la red;
  • el permiso para HTTP en texto plano es un ajuste del archivo [capacitor.config.ts], ubicado en la raíz del proyecto:
// =========================================================================
// capacitor.config.ts - la configuración de Capacitor
// -------------------------------------------------------------------------
// Capacitor convierte la aplicación web (la carpeta producida por ng build)
// en una aplicación Android: la envuelve en un proyecto de Android Studio
// (carpeta android/), donde se muestra en un "WebView", el motor del
// navegador Chrome del teléfono. Comandos (vea el ejemplo 01, "Running"):
//     npx cap add android       (solo una vez: crea la carpeta android/)
//     ng build                  (compila la aplicación web)
//     npx cap sync android      (la copia en el proyecto Android)
//     npx cap run android       (la ejecuta en un emulador o un teléfono)
// =========================================================================

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  // el identificador único de la aplicación en el teléfono (y en Play Store)
  appId: 'fr.stahe.examples',
  // el nombre que se muestra bajo el ícono
  appName: 'Ionic Examples',
  // la carpeta de la aplicación web compilada (ng build)
  webDir: 'dist/examples_ionic/browser',
  server: {
    // permite solicitudes HTTP sin cifrar (http://10.0.2.2:8080) hacia
    // el servidor JSON de desarrollo (ejemplos 22 a 25)
    cleartext: true,
  },
  plugins: {
    // CapacitorHttp: las solicitudes HTTP de la aplicación ya no las realiza
    // el WebView sino el código nativo de Android. Consecuencias (vea los
    // ejemplos 22 y 23): no hay verificación de CORS (el servidor JSON no tiene nada
    // que permitir), y las cookies (la del token de autenticación) las
    // almacena Android y se reenvían automáticamente
    CapacitorHttp: {
      enabled: true,
    },
  },
};

export default config;
  • Líneas 23–27: [server.cleartext: true]. A partir de la versión 9 de [Android], una aplicación solo tiene permitido comunicarse mediante HTTPS. Nuestro servidor de desarrollo usa HTTP: lo permitimos. El comando [npx cap sync android] traslada este ajuste al proyecto [Android] (el atributo [android:usesCleartextTraffic="true"], agregado al manifiesto que [Capacitor] fusiona con el manifiesto de la aplicación). En producción, el servidor estaría en HTTPS y este ajuste desaparecería;
  • líneas 28–37: el plugin [CapacitorHttp]. Las solicitudes HTTP de la aplicación (las del cliente HTTP de [Angular], al igual que las de [fetch]) ya no las envía el WebView sino el código nativo de [Android]. Para un navegador, la aplicación (https://localhost) y el servidor (http://10.0.2.2:8080) parecerían tener dos orígenes distintos: el navegador exigiría que el servidor proporcione una autorización CORS, que el servidor no concede, y se negaría a incluir la cookie del token. El código nativo no tiene estas reglas. El código [TypeScript] de la aplicación, sin embargo, no cambia: es [Capacitor] quien redirige las solicitudes.

9.1.3. ¿Y en el navegador?

Durante el desarrollo, la aplicación se ejecuta en el navegador de la computadora: [ng serve] la sirve en el puerto 8100, mientras que el servidor JSON está en el puerto 8080. Nuevamente, hay dos orígenes, y [CapacitorHttp] no funciona dentro de un navegador. La solución es un proxy, configurado en [angular.json] (opción ["proxyConfig": "proxy.conf.json"] del destino [serve]):

1
2
3
4
5
6
7
8
{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false,
    "changeOrigin": false,
    "logLevel": "warn"
  }
}
  • Línea 2: toda solicitud cuya dirección comience con [/api]...
  • línea 3: ... es reenviada por el servidor de desarrollo de [Angular] al servidor JSON, y su respuesta se devuelve al navegador. Para el navegador, la aplicación y la API tienen el mismo origen (http://localhost:8100): no hay CORS, y la cookie se transmite. Este es exactamente el papel del proxy de [Vite] en el curso de [React], y del archivo [web_dev_config.yaml] en el curso de [Flutter];
  • línea 4: [secure: false]: no exigir un certificado HTTPS válido al destino (de todos modos está en HTTP); línea 6: mostrar solo las advertencias del proxy.

9.1.4. La solicitud

Se solicita un CAPTCHA al servidor: [GET /api/captcha], que responde con [{ "id": "...", "svg": "<svg ...>" }].

// =========================================================================
// src/app/ex22-http/ex22.page.ts - una primera solicitud HTTP al servidor
// -------------------------------------------------------------------------
// El servidor JSON de RdvMedecins debe estar en ejecución (puerto 8080). Se le pide
// un captcha: GET /api/captcha -> { "id": "...", "svg": "<svg ...>" }.
//
//   - HttpClient: el cliente HTTP de Angular (proporcionado a toda la aplicación
//     por provideHttpClient(), en main.ts). http.get<T>(address) devuelve
//     un Observable: la solicitud se envía cuando nos SUSCRIBIMOS a él (subscribe), y
//     la respuesta llega más tarde, con su cuerpo JSON ya decodificado;
//   - una respuesta de error (4xx, 5xx) o la ausencia de respuesta llegan
//     a la función error de la suscripción;
//   - la dirección del servidor depende de dónde se ejecute la aplicación
//     (navegador, emulador de Android, teléfono): véase common/config.ts;
//   - tres estados que mostrar: cargando, con éxito, con error;
//   - la imagen del captcha es SVG: una etiqueta <img> puede mostrarla.
// =========================================================================

import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { Component, DestroyRef, inject, signal } from '@angular/core';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonContent, IonHeader, IonNote, IonProgressBar,
  IonTitle, IonToolbar,
} from '@ionic/angular';
import { Subscription } from 'rxjs';
import { config } from '../common/config';
import { Captcha, captchaImage } from '../common/types';

@Component({
  selector: 'app-ex22',
  imports: [
    IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonProgressBar, IonCard, IonCardContent,
    IonButton, IonNote,
  ],
  templateUrl: './ex22.page.html',
  styles: `
    .error { --background: #ffebee; --color: #333; margin: 12px 0; }
    .image { border: 1px solid #ddd; border-radius: 6px; padding: 4px; text-align: center; }
    .image img { height: 60px; }
    .id { font-family: monospace; font-size: 11px; margin: 8px 0; }
  `,
})
export class Ex22Page {
  private readonly http = inject(HttpClient);
  readonly server = config.serverUrl || '(same origin: /api, ng serve proxy)';
  readonly captchaImage = captchaImage;

  // el estado de la pantalla: señales
  readonly captcha = signal<Captcha | null>(null);
  readonly loading = signal(true);
  readonly error = signal<string | null>(null);
  readonly requestCount = signal(0);

  // la suscripción a la solicitud en curso (si hay una)
  private request?: Subscription;

  constructor() {
    this.load(); // la primera solicitud, apenas se crea la página
    // la página destruida (botón Atrás): la solicitud en curso se abandona
    inject(DestroyRef).onDestroy(() => this.request?.unsubscribe());
  }

  load(): void {
    // darse de baja de una solicitud aún en curso la CANCELA: su respuesta,
    // ahora inútil, nunca se procesará (ninguna respuesta "obsoleta")
    this.request?.unsubscribe();
    this.loading.set(true);
    this.error.set(null);
    // <Captcha>: el tipo del cuerpo JSON esperado (una promesa hecha al
    // compilador: nada se comprueba en tiempo de ejecución)
    this.request = this.http.get<Captcha>(`${config.serverUrl}/api/captcha`).subscribe({
      // next: la respuesta ha llegado (código 2xx), su cuerpo JSON está decodificado
      next: (captcha) => {
        this.captcha.set(captcha);
        this.requestCount.update((n) => n + 1);
        this.loading.set(false);
      },
      // error: una respuesta de error (4xx, 5xx), o ninguna respuesta
      // (servidor detenido, dirección incorrecta: status vale entonces 0)
      error: (e: HttpErrorResponse) => {
        this.error.set(e.status === 0 ? 'no response (status 0)' : `the server responded ${e.status}`);
        this.captcha.set(null);
        this.loading.set(false);
      },
    });
  }
}
<!-- ======================================================================
     ex22.page.html - un captcha solicitado al servidor
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>Example 22 - a first HTTP request</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <ion-note>Server: {{ server }}</ion-note>

  <!-- una barra de progreso "indeterminada" durante la solicitud -->
  @if (loading()) {
    <ion-progress-bar type="indeterminate" class="ion-margin-top" />
  }

  @if (error(); as error) {
    <ion-card class="error">
      <ion-card-content>
        Unable to get a captcha: {{ error }}.<br />
        Is the RdvMedecins JSON server running (port 8080)?
      </ion-card-content>
    </ion-card>
  }

  @if (captcha(); as captcha) {
    @if (!loading()) {
      <!-- la imagen SVG, en forma de dirección data: (véase common/types.ts) -->
      <div class="image ion-margin-top">
        <img [src]="captchaImage(captcha)" alt="captcha" />
      </div>
      <div class="id">id: {{ captcha.id }}</div>
    }
  }

  <!-- deshabilitado durante una solicitud -->
  <ion-button class="ion-margin-top" shape="round" [disabled]="loading()" (click)="load()">Another image</ion-button>
  <p><ion-note>{{ requestCount() }} successful request(s)</ion-note></p>
</ion-content>
  • línea 19 (.ts): [HttpClient], el cliente HTTP de [Angular]. Se proporciona a toda la aplicación mediante [provideHttpClient()], en [main.ts], y la página lo obtiene mediante [inject(HttpClient)] (línea 44);
  • línea 45 (.ts): la dirección del servidor, mostrada en la parte superior de la pantalla; una dirección vacía significa “mismo origen”;
  • líneas 49–52 (.ts): el estado de la pantalla, representado por signals: el CAPTCHA recibido (o [null]), los tres estados de la solicitud (en curso, error, exitosa) y el número de solicitudes exitosas;
  • línea 55 (.ts): la suscripción ([Subscription]) a la solicitud actual;
  • líneas 57–61 (.ts): la primera solicitud se envía en cuanto se carga la página. [DestroyRef] avisa cuando se cierra la página (botón Atrás): la suscripción a la solicitud actual se cancela entonces;
  • líneas 63–86 (.ts): la solicitud:
  • línea 71 (.ts): [this.http.get<Captcha>(address)] todavía no envía la solicitud; devuelve un [Observable] (ejemplo 19) de la respuesta. La solicitud se envía cuando se realiza una suscripción ([subscribe]). El tipo [<Captcha>] es el del cuerpo JSON esperado: una promesa hecha al compilador, que no se verifica en tiempo de ejecución;
  • líneas 73–77 (.ts): [next] recibe la respuesta si su código de estado es 2xx. Su cuerpo, JSON, ya está decodificado: es un objeto [JavaScript] (el paquete [http] de [Flutter] devolvía texto, que había que pasar a [jsonDecode]);
  • líneas 80–84 (.ts): [error] recibe un [HttpErrorResponse], que indica una respuesta de error (4xx, 5xx) o la ausencia de respuesta (servidor caído, dirección incorrecta, falla de red). Se distinguen mediante [e.status], que vale 0 cuando el servidor no ha respondido. Esto difiere de [http.get] y de [Flutter], que trataban una respuesta 4xx o 5xx como una respuesta normal, lo que obligaba a verificar el código;
  • línea 66 (.ts): si la solicitud anterior no ha terminado, se abandona: cancelar la suscripción a una solicitud HTTP la cancela (el navegador la interrumpe), y su respuesta nunca se procesará. Aquí es donde [Observable] demuestra su ventaja sobre [Promise], que no se puede cancelar: el ejemplo de [Flutter] tenía que numerar sus solicitudes para ignorar las respuestas obsoletas;
  • líneas 18–20 (html): una barra de progreso ([<ion-progress-bar type="indeterminate">]) durante la solicitud;
  • líneas 22–29 (html): el error, mostrado en una tarjeta;
  • líneas 31–39 (html): el CAPTCHA. [@if (captcha(); as captcha)] asigna un nombre al valor de la signal cuando no es [null];
  • línea 35 (html): la imagen del CAPTCHA es SVG, en forma de texto. Una etiqueta [<img>] puede mostrarla, siempre que se le entregue en forma de URL; este es el papel de la función [captchaImage] en [common/types.ts]:
// el texto SVG -> una dirección "data:" utilizable por <img [src]>: la imagen
// está EN la dirección. Una imagen SVG mostrada por <img> no puede ejecutar
// ningún script: sin riesgo, aunque su contenido fuera dudoso
export function captchaImage(c: Captcha): string {
  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(c.svg)}`;
}
  • línea 32: una dirección [data:] contiene el propio archivo: su tipo ([image/svg+xml]), seguido de su contenido, codificado por [encodeURIComponent] para que pueda aparecer en una dirección. ¿Por qué no insertar el texto SVG directamente en la página mediante [[innerHTML]]? [Angular] lo rechazaría: un SVG puede contener scripts, y [Angular] “limpia” cualquier HTML insertado de este modo eliminando las etiquetas que no reconoce como seguras, incluida [<svg>]. Podríamos forzarlo ([DomSanitizer.bypassSecurityTrustHtml]), pero una imagen es más sencilla y no presenta riesgos: una imagen mostrada por [<img>] nunca ejecuta scripts. En [Flutter], era el paquete [flutter_svg] el que renderizaba el SVG;
  • línea 42 (html): “Otra imagen”, deshabilitado durante una solicitud.

En el navegador, con el proxy de [ng serve]; entonces el servidor no responde (en esta captura, el script de captura hace fallar la solicitud, igual que lo haría un servidor detenido):

Las herramientas de desarrollo de [Chrome] (F12), en la pestaña “Network”, muestran cada solicitud HTTP de la aplicación, con sus encabezados y su cuerpo: aquí, [GET http://localhost:8100/api/captcha], transmitida a través del proxy. En el teléfono, la aplicación se inspecciona desde la computadora en la dirección [chrome://inspect] (vea el capítulo “Despliegue”); las solicitudes que pasan por [CapacitorHttp], es decir, por el código nativo, se ven menos allí.

El cliente HTTP de [Angular] también ofrece, a partir de la versión 19, [httpResource()]: el equivalente, para una solicitud GET, de [resource()] del Ejemplo 19. Se le proporciona la dirección y devuelve un objeto de signals ([isLoading()], [value()], [error()], [reload()]): toda la gestión de los tres estados de este ejemplo cabría en una sola línea. Para una primera solicitud, elegimos escribir nosotros mismos estos estados; el caso de estudio usará [resource()].

El servidor guarda el token JWT en una cookie. El cliente [Flutter] tenía, en este punto, que reemplazar su cliente HTTP por uno que lee el encabezado [Set-Cookie] de cada respuesta, organiza las cookies (y las almacena en el dispositivo), y las devuelve en el encabezado [Cookie] de cada solicitud: una aplicación [Flutter] no dispone de un navegador que lo haga por ella.

Una aplicación [Ionic], en cambio, no tiene nada que escribir:

  • en el navegador de la computadora, es el navegador quien almacena la cookie y la devuelve, como lo hace con cualquier otro sitio web. El proxy de [ng serve] asigna el mismo origen a la aplicación y a la API: la cookie [SameSite=Strict] se acepta y se devuelve. El código de la aplicación no puede leer ni escribir esta cookie ([HttpOnly]);
  • en [Android], el complemento [CapacitorHttp] (ejemplo 22) hace pasar las solicitudes por el código nativo. [Capacitor] configura, al iniciar la aplicación, el administrador de cookies de [Android] (el del WebView) como administrador de las solicitudes nativas: las cookies recibidas se almacenan allí y se devuelven en las solicitudes siguientes al mismo servidor. Se conservan en el dispositivo (la nuestra tiene una duración definida por [Max-Age=7200]; solo se eliminan al iniciar la aplicación las cookies de “sesión”, que no tienen hora de expiración): la sesión permanece abierta al cerrar y volver a abrir la aplicación.

Por lo tanto, el código de la aplicación nunca manipula el token, ni este se almacena en texto plano en el dispositivo (el cliente [Flutter] lo guardaba en [shared_preferences]).

9.2.2. Un comando

// =========================================================================
// src/app/ex23-login/command.ts - una ACCIÓN, su estado, su resultado
// -------------------------------------------------------------------------
// Una acción asíncrona (iniciar sesión, guardar...) tiene un estado que
// la pantalla debe mostrar: ¿está EN CURSO (botón deshabilitado)? ¿terminó
// con un ERROR (mensaje)? Es el patrón "Command" de las guías de
// arquitectura (la de Flutter, por ejemplo), reducido a lo esencial:
//
//     readonly loginCommand = new Command();
//     this.loginCommand.execute(() => this.logIn());   // inicia la acción
//     loginCommand.running(), loginCommand.error()      // su estado
//
// Su estado está formado por SEÑALES: la plantilla que las lee se actualiza
// cuando el comando se inicia y cuando termina.
// =========================================================================

import { signal } from '@angular/core';

export class Command {
  private readonly _running = signal(false);
  private readonly _error = signal<unknown>(null);
  readonly running = this._running.asReadonly();
  readonly error = this._error.asReadonly();

  // ejecuta la acción, si no hay otra en curso
  async execute(action: () => Promise<void>): Promise<void> {
    if (this._running()) return; // sin doble envío (doble toque en el botón)
    this._running.set(true);
    this._error.set(null);
    try {
      await action();
    } catch (e) {
      this._error.set(e); // el error se CONSERVA, para mostrarlo
    } finally {
      // finally: se ejecuta en TODOS los casos, éxito o error
      this._running.set(false);
    }
  }

  clearError(): void {
    this._error.set(null);
  }
}

Una acción asíncrona (iniciar sesión, guardar, etc.) tiene un estado que la pantalla debe mostrar: ¿está en curso (botón deshabilitado)? ¿Terminó con un error (mensaje)? Este es el modelo “Command” de las guías de arquitectura (el de [Flutter] lo llama así), reducido a lo esencial. El curso de [React] usaba para ello las “acciones” de [React] 19 ([useActionState]).

  • Líneas 19–23: una clase simple (cada pantalla crea la suya con [new]), cuyo estado consta de dos signals privados, expuestos como de solo lectura. La plantilla que lee [running()] o [error()] se actualiza cuando el comando comienza y cuando termina: es el papel que [ChangeNotifier] y [ListenableBuilder] desempeñaban en [Flutter];
  • líneas 26–38: ejecutar una acción: si otra acción está en curso, no hace nada (línea 27: evita el doble envío si se presiona el botón dos veces); de lo contrario, el comando pasa a “en curso”; en caso de excepción, se registra el error para mostrarlo (línea 33); en todos los casos ([finally], líneas 34–37), el comando deja de estar en curso. El error es de tipo [unknown]: en [JavaScript], se puede lanzar cualquier valor, y [TypeScript] por lo tanto no sabe qué es lo que [catch] captura.

9.2.3. La pantalla

// =========================================================================
// src/app/ex23-login/ex23.page.ts - inicio de sesión en el servidor de RdvMedecins
// -------------------------------------------------------------------------
//   1. al iniciar: GET /api/auth/me - ¿ya hay una sesión iniciada?
//      (la aplicación pudo haberse detenido; el servidor, por su parte, lee la cookie
//      que se le presenta);
//   2. inicio de sesión: POST /api/auth/login, cuerpo JSON { login, password,
//      captchaId, captcha }. Si tiene éxito, el servidor envía la cookie
//      del token JWT (encabezado Set-Cookie);
//   3. solicitud protegida: GET /api/doctors. La cookie la acompaña.
//   4. cierre de sesión: POST /api/auth/logout - el servidor elimina la cookie.
// ¿Y la cookie? El código NO tiene NADA que hacer: en un navegador, es el
// navegador quien la almacena y la reenvía; en Android, es el código nativo
// (plugin CapacitorHttp, véase capacitor.config.ts).
// =========================================================================

import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { Component, inject, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonContent, IonHeader, IonInput, IonNote, IonText,
  IonTitle, IonToolbar,
} from '@ionic/angular';
import { firstValueFrom } from 'rxjs';
import { config } from '../common/config';
import { Captcha, captchaImage } from '../common/types';
import { Command } from './command';

// los pocos mensajes que necesita este ejemplo (el ejemplo 25 usará diccionarios)
const messages: Record<string, string> = {
  'LOGIN.ERROR': 'Incorrect login or password.',
  'ERRORS.WRONG_CAPTCHA': 'The characters you typed do not match the image.',
  'ERRORS.TOO_MANY_ATTEMPTS': 'Too many failed attempts. Try again later.',
};

// lo que devuelven POST /api/auth/login y GET /api/auth/me, y una fila de GET /api/doctors
interface User {
  login: string;
  name: string;
  role: string;
}
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
}

@Component({
  selector: 'app-ex23',
  imports: [
    FormsModule, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonCard, IonCardContent,
    IonInput, IonButton, IonText, IonNote,
  ],
  templateUrl: './ex23.page.html',
  styles: `
    .captcha { display: flex; align-items: center; margin-top: 12px; }
    .captcha img { height: 50px; }
    .error { --background: #ffebee; --color: #333; }
    h3 { font-size: 14px; font-weight: bold; margin: 12px 0 4px; }
  `,
})
export class Ex23Page {
  private readonly http = inject(HttpClient);
  readonly captchaImage = captchaImage;

  readonly user = signal<User | null>(null); // null: nadie ha iniciado sesión
  readonly doctors = signal<Doctor[]>([]);
  readonly captcha = signal<Captcha | null>(null);
  readonly ready = signal(false); // ¿ha terminado la comprobación inicial?
  readonly serverError = signal<string | null>(null);
  readonly loginCommand = new Command();
  // los campos del formulario, enlazados por [(ngModel)]
  readonly login = signal('admin');
  readonly password = signal('');
  readonly captchaAnswer = signal('');

  constructor() {
    this.checkSession();
  }

  private url(path: string): string {
    return `${config.serverUrl}/api${path}`;
  }

  // una solicitud GET cuyo cuerpo JSON queremos. Una respuesta que no sea 2xx
  // (o la ausencia de respuesta) rechaza la Promise con un HttpErrorResponse
  private read<T>(path: string): Promise<T> {
    return firstValueFrom(this.http.get<T>(this.url(path)));
  }

  // un POST: el objeto del cuerpo se envía como JSON (encabezado content-type: application/json)
  private post<T>(path: string, body: object): Promise<T> {
    return firstValueFrom(this.http.post<T>(this.url(path), body));
  }

  async loadCaptcha(): Promise<void> {
    this.captcha.set(await this.read<Captcha>('/captcha'));
    this.captchaAnswer.set('');
  }

  private async loadDoctors(): Promise<void> {
    this.doctors.set(await this.read<Doctor[]>('/doctors'));
  }

  // 1. ¿quién ha iniciado sesión? 200 -> el usuario; 401 -> nadie
  private async checkSession(): Promise<void> {
    try {
      this.user.set(await this.read<User>('/auth/me'));
      await this.loadDoctors();
    } catch (e) {
      // instanceof: una prueba de TIPO; e.status: el código de estado (0: sin respuesta)
      if (e instanceof HttpErrorResponse && e.status === 401) {
        await this.loadCaptcha();
      } else if (e instanceof HttpErrorResponse && e.status !== 0) {
        this.serverError.set(`The server responded ${e.status}.`);
      } else {
        this.serverError.set(`Is the RdvMedecins JSON server running (${config.serverUrl || 'port 8080'})?`);
      }
    }
    this.ready.set(true);
  }

  // el botón "Iniciar sesión": el Command ejecuta la acción y almacena su error
  submit(): void {
    this.loginCommand.execute(() => this.logIn());
  }

  // 2. el inicio de sesión
  private async logIn(): Promise<void> {
    try {
      const user = await this.post<User>('/auth/login', {
        login: this.login().trim(),
        password: this.password(),
        captchaId: this.captcha()?.id,
        captcha: this.captchaAnswer(),
      });
      this.password.set('');
      this.user.set(user);
      await this.loadDoctors();
    } catch (e) {
      if (!(e instanceof HttpErrorResponse)) throw e;
      // e.error: el cuerpo JSON de la respuesta de error, { statusCode, key, ... }
      const key: string = e.error?.key ?? 'ERRORS.SERVER_UNREACHABLE';
      await this.loadCaptcha(); // cada imagen se usa una sola vez
      // el error que el Command conservará
      throw new Error(`${e.status} - ${messages[key] ?? key}`);
    }
  }

  // el mensaje del error conservado por el comando
  errorMessage(): string {
    const error = this.loginCommand.error();
    return error instanceof Error ? error.message : String(error);
  }

  // 4. el cierre de sesión
  async logOut(): Promise<void> {
    await this.post('/auth/logout', {});
    this.user.set(null);
    this.doctors.set([]);
    await this.loadCaptcha();
  }
}
<!-- ======================================================================
     ex23.page.html - inicio de sesión, sesión, cierre de sesión
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>Example 23 - logging in to the server</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  @if (!ready()) {
    <ion-note>Checking the session...</ion-note>
  } @else if (user(); as u) {
    <!-- sesión iniciada -->
    <ion-card>
      <ion-card-content>
        <div>Logged in: <strong>{{ u.name }}</strong> ({{ u.login }}), role {{ u.role }}</div>
        <!-- 3. una solicitud protegida: la cookie la acompañó -->
        <h3>GET /api/doctors</h3>
        @for (m of doctors(); track m.id) {
          <div>• {{ m.title }} {{ m.firstName }} {{ m.lastName }}</div>
        }
        <p class="ion-margin-top"><ion-note>Stop then restart the application: you stay logged in.</ion-note></p>
        <ion-button fill="outline" shape="round" (click)="logOut()">Log out</ion-button>
      </ion-card-content>
    </ion-card>
  } @else if (serverError() === null) {
    <!-- sin sesión iniciada: el formulario -->
    <ion-card>
      <ion-card-content>
        <ion-input label="Login" labelPlacement="floating" [(ngModel)]="login" />
        <ion-input label="Password" labelPlacement="floating" type="password" [(ngModel)]="password" />
        <div class="captcha">
          @if (captcha(); as c) {
            <img [src]="captchaImage(c)" alt="captcha" />
          }
          <ion-button fill="clear" size="small" (click)="loadCaptcha()">Another image</ion-button>
        </div>
        <ion-input label="Copy the characters of the image" labelPlacement="floating" autocorrect="off"
          autocapitalize="off" [(ngModel)]="captchaAnswer" />
        <!-- el botón sigue el estado del comando -->
        <ion-button class="ion-margin-top" shape="round" [disabled]="loginCommand.running()"
          (click)="submit()">
          {{ loginCommand.running() ? 'Logging in...' : 'Log in' }}
        </ion-button>
        @if (loginCommand.error() !== null) {
          <p><ion-text color="danger">{{ errorMessage() }}</ion-text></p>
        }
        <p><ion-note>Accounts: admin, pelissier, martin... (password = login).</ion-note></p>
      </ion-card-content>
    </ion-card>
  }

  @if (serverError(); as message) {
    <ion-card class="error">
      <ion-card-content>{{ message }}</ion-card-content>
    </ion-card>
  }
</ion-content>

La pantalla recorre las cuatro etapas de una sesión: al iniciar, ¿quién ha iniciado sesión?; el inicio de sesión; una solicitud protegida; y el cierre de sesión.

  • líneas 29–34 (.ts): los pocos mensajes que requiere este ejemplo (el Ejemplo 25 usará diccionarios);
  • líneas 36–47 (.ts): el formato de las respuestas utilizadas, descrito mediante dos interfaces (el Ejemplo 24 almacenará estos tipos en [common/types.ts]);
  • líneas 67–76 (.ts): el estado: el usuario con sesión iniciada ([null]: nadie), los médicos, el CAPTCHA, la finalización de la verificación inicial, un error del servidor, el comando de inicio de sesión y los campos del formulario;
  • Líneas 86–95 (.ts): dos atajos. [firstValueFrom(observable)] (de [RxJS]) se suscribe al [Observable] de la solicitud y devuelve una [Promise] con su primer valor, la respuesta: así se puede esperar con [await], en un código que se lee de arriba abajo. Si la solicitud falla, la [Promise] se rechaza con la [HttpErrorResponse], y [await] la lanza como una excepción. Para un POST (línea 94), el cuerpo es un objeto: el cliente HTTP lo envía como JSON, con el encabezado [Content-Type: application/json] que exige el servidor (de lo contrario: 415);
  • líneas 107–122 (.ts): 1. Al iniciar, ¿quién ha iniciado sesión? [GET /api/auth/me]: 200, el usuario (seguido de la lista de médicos); 401 (línea 113), nadie: se carga un CAPTCHA para el formulario. [e instanceof HttpErrorResponse] es una verificación de tipo: en la rama donde es verdadera, [TypeScript] sabe que [e] tiene un [status]. Otro código de error (líneas 115–116) o ninguna respuesta (líneas 117–119, [status] 0): un mensaje;
  • líneas 125–127 (.ts): el botón “Iniciar sesión” delega la acción en el comando;
  • líneas 130–149 (.ts): 2. la conexión: [POST /api/auth/login]. Si tiene éxito, el navegador (o [Android]) ha almacenado la cookie: se conserva el usuario y se cargan los médicos. Si la conexión falla, [e.error] es el cuerpo de la respuesta de error, ya decodificado: contiene la clave del mensaje (línea 144; [?.] y [??]: una clave de respaldo si el cuerpo no contiene ninguna). Se carga una nueva imagen (cada una se usa una sola vez) y luego se lanza un error cuyo mensaje se mostrará (línea 147): es el comando quien lo captura y lo almacena. Una excepción que no sea una [HttpErrorResponse] (una anomalía) se vuelve a lanzar tal cual (línea 142);
  • líneas 152–155 (.ts): el mensaje de error conservado por el comando;
  • líneas 158–163 (.ts): 4. Cierre de sesión: [POST /api/auth/logout]; el servidor elimina la cookie (envía una cookie vacía que ya expiró) y el navegador la olvida;
  • líneas 15–16 (html): mientras la verificación inicial no haya terminado;
  • líneas 17–30 (html): 3. con sesión iniciada: el usuario y la lista de médicos ([GET /api/doctors], una solicitud protegida: la cookie se incluyó sin una sola línea de código);
  • líneas 31–55 (HTML): sin sesión iniciada: el formulario. Los campos se enlazan a los signals mediante [[(ngModel)]] (ejemplo 05); el CAPTCHA se muestra como en el ejemplo 22 (líneas 38–40);
  • líneas 46–52 (HTML): el botón refleja el estado de la solicitud: deshabilitado y con “Iniciando sesión...” mientras se envía la solicitud; cualquier mensaje de error aparece debajo;
  • líneas 58–62 (HTML): el servidor no responde.

La pantalla de inicio de sesión; una contraseña incorrecta; inicio de sesión exitoso:

Recargue la página del navegador (o, en un teléfono, cierre y vuelva a abrir la aplicación): se abre con la sesión iniciada. La cookie, almacenada por el navegador (o por [Android]), se envía a [GET /api/auth/me], y el servidor responde con las credenciales del usuario. El token expira a las dos horas: [GET /api/auth/me] devolverá entonces una respuesta 401 y volverá a aparecer la pantalla de inicio de sesión.

9.3. Ejemplo 24: una capa de acceso a la API

En el Ejemplo 23, cada solicitud repetía los mismos pasos. Este ejemplo los organiza en tres capas, que el caso de estudio retomará.

9.3.1. Los tipos

// =========================================================================
// src/app/common/types.ts - los objetos JSON intercambiados con la API de RdvMedecins
// (véase el capítulo sobre la caja negra, que describe cada ruta)
// -------------------------------------------------------------------------
// La traducción, a tipos de TypeScript, de las respuestas del servidor. Son
// solo DESCRIPCIONES: desaparecen en tiempo de compilación y no
// comprueban nada en tiempo de ejecución. Permiten que el compilador
// verifique que el código solo usa campos que existen, con el tipo
// correcto (y que el editor sugiera sus nombres).
// =========================================================================

// un "tipo unión" de cadenas: solo se permiten estos tres valores
export type Role = 'ADMIN' | 'DOCTOR' | 'USER';

// POST /api/auth/login, GET /api/auth/me
export interface User {
  login: string;
  name: string; // nombre mostrado: "Marie PELISSIER"
  role: Role;
}

// GET /api/captcha
export interface Captcha {
  id: string;
  svg: string; // la imagen, en formato SVG (texto)
}

// el texto SVG -> una dirección "data:" utilizable por <img [src]>: la imagen
// está EN la dirección. Una imagen SVG mostrada por <img> no puede ejecutar
// ningún script: sin riesgo, aunque su contenido fuera dudoso
export function captchaImage(c: Captcha): string {
  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(c.svg)}`;
}

// el nombre de una persona, y nada más
export interface Identity {
  title: string;
  firstName: string;
  lastName: string;
}

// un médico o un cliente (GET /api/doctors, GET /api/clients...)
// "extends": una Person tiene todos los campos de una Identity, y otros más
export interface Person extends Identity {
  id: number;
  version: number; // bloqueo optimista: debe reenviarse con una actualización
  login?: string; // opcional (?): solo para el ADMIN
}

// "Mme Alice DURAND"
export function fullName(i: Identity): string {
  return `${i.title} ${i.firstName} ${i.lastName}`;
}

// una fila de GET /api/schedule: una franja, y los DERECHOS del usuario con sesión iniciada
export interface ScheduleSlot {
  id: number;
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
  free: boolean;
  patient: Identity | null; // null: libre, u ocupada por otro paciente
  mine: boolean; // la cita del paciente con sesión iniciada
  bookable: boolean;
  appointmentId: number | null; // definido si el usuario puede cancelar
}

// "8:00 - 8:20"
export function timeRange(c: ScheduleSlot): string {
  const hm = (h: number, m: number) => `${h}:${String(m).padStart(2, '0')}`;
  return `${hm(c.startHour, c.startMinute)} - ${hm(c.endHour, c.endMinute)}`;
}

// GET /api/schedule?doctorId=...&day=...
export interface Schedule {
  doctor: Person;
  day: string; // "yyyy-MM-dd"
  slots: ScheduleSlot[];
  info: string | null; // clave de traducción (paciente que ya tiene una cita)
}

Las respuestas del servidor, descritas en [TypeScript]. Son simples descripciones: las interfaces se eliminan en la compilación y no realizan ninguna verificación durante la ejecución. Permiten que el compilador verifique que el código solo usa campos que existen, con el tipo correcto, y que el editor sugiera sus nombres.

  • línea 13: un tipo de unión de cadenas: a una variable de tipo [Role] solo se le puede asignar una de estas tres cadenas. El compilador rechaza [role === 'ADMN'];
  • líneas 16–20: el usuario con sesión iniciada ([POST /api/auth/login], [GET /api/auth/me]);
  • líneas 44–48: una persona (médico o cliente). [extends Identity]: tiene todos los campos de una [Identity] (líneas 36–40), además de otros; [login?]: un campo opcional (solo lo contiene el ADMIN);
  • líneas 56–67: una entrada de la agenda. [Identity | null], [number | null]: junto con ["strict": true] y [TypeScript], esto obliga a comprobar estos valores antes de usarlos;
  • líneas 51–53, 70–73: funciones de formato: “Mme Alice DURAND”, “8:00 – 8:20”. No son métodos: los objetos recibidos del servidor son objetos ordinarios de [JavaScript], sin clase;
  • líneas 76–81: la agenda de un médico para un día.

Esta es una diferencia fundamental con el cliente [Flutter]. En [Dart], el JSON decodificado no tiene tipo ([dynamic]): cada clase tenía un constructor [fromJson], que verificaba el formato del JSON recibido mediante el filtrado de [Dart] 3 (“pattern matching”), y lo convertía en un objeto. Aquí, el compilador acepta lo que se le dice sin cuestionarlo ([http.get<Schedule>(...)]): una respuesta inesperada solo se detectaría cuando la pantalla encontrara un campo faltante. Para un servidor bajo nuestro control, es una práctica habitual. Para una API externa, verificaríamos las respuestas con una biblioteca de “esquemas” ([Zod], [Valibot]), que realiza en tiempo de ejecución lo que antes hacía el filtrado de [Dart].

9.3.2. Errores

// =========================================================================
// src/app/common/api-error.ts - UNA clase para todos los errores de la API
// -------------------------------------------------------------------------
// Todas las respuestas de error del servidor de RdvMedecins tienen la misma forma:
//   { "statusCode": 409, "key": "ERRORS.LOGIN_TAKEN", "params": {...}, "fields": {...} }
// Pero una solicitud también puede fallar de OTRO modo: ninguna respuesta
// (red caída, servidor detenido, dirección incorrecta), o una respuesta que no
// proviene de nuestro servidor (una página de error de un proxy). El cliente HTTP
// de Angular informa de todos estos fallos con un HttpErrorResponse; lo
// convertimos en UNA sola clase, ApiError, que lleva la clave de traducción
// enviada por el servidor (y, si los hay, sus parámetros y el error de
// cada campo).
// =========================================================================

import { HttpErrorResponse } from '@angular/common/http';

// un objeto { name: texto }
export type Texts = Record<string, string>;

// "extends Error": un error de JavaScript de pleno derecho, que lanzamos
// (throw) y capturamos (catch); message vale "409 ERRORS.LOGIN_TAKEN"
export class ApiError extends Error {
  constructor(
    readonly statusCode: number, // 0: el servidor no respondió
    readonly key: string, // p. ej.: 'ERRORS.LOGIN_TAKEN'
    readonly params: Texts = {},
    readonly fields: Texts = {},
  ) {
    super(`${statusCode} ${key}`);
    this.name = 'ApiError';
  }

  // una respuesta de error del cliente HTTP de Angular -> un ApiError
  static fromResponse(response: HttpErrorResponse): ApiError {
    // status 0: sin respuesta (red caída, servidor detenido, dirección incorrecta)
    if (response.status === 0) {
      return new ApiError(0, 'ERRORS.SERVER_UNREACHABLE');
    }
    // error: el cuerpo de la respuesta, ya decodificado si es JSON
    const body: unknown = response.error;
    if (isObject(body) && typeof body['key'] === 'string') {
      return new ApiError(response.status, body['key'], texts(body['params']), texts(body['fields']));
    }
    // sin key: el proxy o la red respondieron en su lugar
    return new ApiError(
      response.status,
      response.status >= 500 ? 'ERRORS.SERVER_UNREACHABLE' : 'ERRORS.SERVER_ERROR',
    );
  }
}

// un "type guard": si la función devuelve true, TypeScript sabe que
// value es un objeto cuyas propiedades se pueden leer
function isObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

// un objeto JSON { "name": "ERRORS..." } -> Texts (vacío en caso contrario)
function texts(json: unknown): Texts {
  if (!isObject(json)) return {};
  return Object.fromEntries(Object.entries(json).map(([key, value]) => [key, String(value)]));
}

Todas las respuestas de error del servidor tienen el mismo formato. Sin embargo, una solicitud también puede fallar de OTRA manera: ninguna respuesta, o una respuesta que no proviene de nuestro servidor. El cliente HTTP de [Angular] notifica todos estos fallos como una [HttpErrorResponse]; los convertimos en UNA sola clase, [ApiError].

  • Línea 18: [Record<string, string>]: un objeto cuyas propiedades son cadenas;
  • líneas 22–31: [extends Error]: un error de pleno derecho de [JavaScript], que se lanza ([throw]) y se captura ([catch]), junto con su pila de llamadas. Los parámetros del constructor precedidos por [readonly] declaran e inicializan los campos (una abreviatura de [TypeScript]): un estado (0: ninguna respuesta), una clave de traducción, sus parámetros y el error de cada campo. El mensaje del error (línea 29) es “401 LOGIN.ERROR”, para una visualización rápida;
  • líneas 34–49: una [HttpErrorResponse] → una [ApiError]. Estado 0: ninguna respuesta (líneas 36–38). De lo contrario, [response.error] es el cuerpo de la respuesta, ya decodificado si es JSON (línea 40); si tiene una clave de tipo cadena [key], respondió nuestro servidor (líneas 41–42). De lo contrario, un intermediario (proxy, red) respondió en su lugar (líneas 45–48);
  • líneas 54–56: un type guard ([value is Record<string, unknown>]): una función cuyo resultado, [true], informa al compilador del tipo de su parámetro. Después de [isObject(body)], sabe que [body] es un objeto cuyas propiedades se pueden leer. Esto es lo que hacía en un solo paso la instrucción “if-case” de [Dart];
  • líneas 59–62: un objeto JSON { "name": "ERRORS..." } → texto (vacío si no es un objeto).

9.3.3. Las solicitudes

// =========================================================================
// src/app/common/api.ts - solicitudes a la API, en una línea
// -------------------------------------------------------------------------
// En el ejemplo 23, cada solicitud repetía los mismos pasos: dirección del
// servidor, prefijo /api, conversión del Observable en Promise, lectura
// del cuerpo del error... Los agrupamos aquí, en un SERVICIO:
//
//   const doctors = await this.api.get<Person[]>('/doctors');
//   await this.api.post('/appointments', { day, slotId: 3 });
//
//   - si tiene éxito, la Promise devuelve el cuerpo JSON, DECODIFICADO;
//   - si falla, se rechaza con un ApiError.
// Todas las solicitudes pasan por el método request: es el lugar donde
// trataríamos un problema COMÚN a todas ellas (véase el caso de estudio y la
// respuesta 401). Usado por los ejemplos 24 y 25.
// =========================================================================

import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { inject, Injectable } from '@angular/core';
import { firstValueFrom } from 'rxjs';
import { config } from './config';
import { ApiError } from './api-error';

export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

// providedIn: 'root': una sola instancia, para toda la aplicación
@Injectable({ providedIn: 'root' })
export class Api {
  private readonly http = inject(HttpClient);

  // <T>: el tipo de la respuesta esperada, elegido por quien llama
  async request<T>(method: Method, url: string, body?: unknown): Promise<T> {
    try {
      // http.request devuelve un Observable; firstValueFrom lo convierte en
      // Promise (la solicitud se envía en ese momento). Un objeto de cuerpo se envía
      // como JSON (encabezado content-type: application/json, que el servidor exige
      // en un POST); la respuesta JSON se decodifica (null si su cuerpo está vacío)
      return await firstValueFrom(this.http.request<T>(method, `${config.serverUrl}/api${url}`, { body }));
    } catch (e) {
      // el cliente HTTP informa de CUALQUIER fallo (4xx, 5xx, sin respuesta) con un
      // HttpErrorResponse: lo convertimos. El resto (una anomalía) pasa tal cual
      throw e instanceof HttpErrorResponse ? ApiError.fromResponse(e) : e;
    }
  }

  get<T>(url: string): Promise<T> {
    return this.request<T>('GET', url);
  }

  // un POST siempre tiene un cuerpo JSON: {} por defecto
  post<T>(url: string, body: unknown = {}): Promise<T> {
    return this.request<T>('POST', url, body);
  }

  put<T>(url: string, body: unknown): Promise<T> {
    return this.request<T>('PUT', url, body);
  }

  delete<T>(url: string, body?: unknown): Promise<T> {
    return this.request<T>('DELETE', url, body);
  }
}

Un servicio (Ejemplo 14) que realiza, de una vez por todas, las acciones repetidas en el Ejemplo 23:

  • línea 27: [@Injectable({ providedIn: 'root' })]: una única instancia, para toda la aplicación, creada en la primera solicitud;
  • Líneas 32–44: TODAS las solicitudes se procesan con este método: la dirección del servidor y el prefijo [/api], el cuerpo en JSON ([http.request] acepta todos los métodos, y un cuerpo incluso para un DELETE), la respuesta decodificada y esperada con [firstValueFrom] (línea 38), los errores convertidos en [ApiError] (línea 42). El tipo de respuesta [<T>] lo elige quien llama ([api.get<Person[]>('/doctors')]). Aquí es donde se trataría un problema común a todas las solicitudes (vea el caso de estudio, y la respuesta 401 de una sesión expirada, que se trata en un interceptor del cliente HTTP);
  • líneas 46–61: cuatro atajos. Un POST siempre tiene un cuerpo JSON: [{}] por defecto (línea 51).

9.3.4. Una barra de conexión

// =========================================================================
// src/app/common/login-bar.ts - inicio / cierre de sesión, en una sola barra
// -------------------------------------------------------------------------
// El formulario del ejemplo 23, reducido a una barra y reescrito con el
// servicio Api. El componente emite el evento userChange con
// el usuario con sesión iniciada (o null) cada vez que cambia, incluido
// al iniciar, tras consultar GET /api/auth/me:
//
//     <app-login-bar (userChange)="onUserChange($event)" />
//
// El servicio Api se obtiene por inyección de dependencias (inject).
// =========================================================================

import { Component, inject, output, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { IonButton, IonCard, IonCardContent, IonIcon, IonInput, IonLabel, IonText } from '@ionic/angular';
import { addIcons } from 'ionicons';
import { logInOutline, person } from 'ionicons/icons';
import { Api } from './api';
import { ApiError } from './api-error';
import { Captcha, captchaImage, User } from './types';

@Component({
  selector: 'app-login-bar',
  imports: [FormsModule, IonCard, IonCardContent, IonInput, IonButton, IonIcon, IonLabel, IonText],
  templateUrl: './login-bar.html',
  styles: `
    ion-card { --background: #eceff1; margin: 0 0 8px; }
    ion-card-content { padding: 8px 12px; }
    .line { display: flex; align-items: center; gap: 8px; }
    .line > ion-input, .line > ion-label { flex: 1; }
    img { height: 40px; }
    .error { font-size: 13px; }
  `,
})
export class LoginBar {
  private readonly api = inject(Api);
  readonly captchaImage = captchaImage;

  // el evento emitido al padre: el usuario con sesión iniciada, o null
  readonly userChange = output<User | null>();

  readonly user = signal<User | null>(null);
  readonly captcha = signal<Captcha | null>(null);
  readonly login = signal('admin');
  readonly password = signal('');
  readonly captchaAnswer = signal('');
  readonly error = signal<string | null>(null);

  constructor() {
    addIcons({ person, logInOutline });
    this.start();
  }

  private change(u: User | null): void {
    this.user.set(u);
    this.userChange.emit(u);
  }

  private async newCaptcha(): Promise<void> {
    this.captcha.set(await this.api.get<Captcha>('/captcha'));
    this.captchaAnswer.set('');
  }

  // al iniciar: ¿ya hay una sesión iniciada?
  private async start(): Promise<void> {
    try {
      this.change(await this.api.get<User>('/auth/me'));
    } catch {
      this.change(null); // 401: nadie ha iniciado sesión
      try {
        await this.newCaptcha();
      } catch {
        this.error.set('Is the JSON server running (port 8080)?');
      }
    }
  }

  async logIn(): Promise<void> {
    this.error.set(null);
    try {
      const u = await this.api.post<User>('/auth/login', {
        login: this.login().trim(),
        password: this.password(),
        captchaId: this.captcha()?.id,
        captcha: this.captchaAnswer(),
      });
      this.password.set('');
      this.change(u);
    } catch (e) {
      // e.message: "401 LOGIN.ERROR" (el ejemplo 25 traducirá la clave)
      this.error.set(e instanceof ApiError ? e.message : String(e));
      await this.newCaptcha();
    }
  }

  async logOut(): Promise<void> {
    await this.api.post('/auth/logout');
    this.change(null);
    await this.newCaptcha();
  }
}
<!-- ======================================================================
     login-bar.html - el usuario con sesión iniciada, o un pequeño formulario
     ====================================================================== -->

<ion-card>
  <ion-card-content>
    @if (user(); as u) {
      <div class="line">
        <ion-icon name="person" />
        <ion-label>{{ u.name }} ({{ u.role }})</ion-label>
        <ion-button fill="clear" size="small" (click)="logOut()">Log out</ion-button>
      </div>
    } @else {
      <div class="line">
        <ion-input label="login" labelPlacement="floating" [(ngModel)]="login" />
        <ion-input label="password" labelPlacement="floating" type="password" [(ngModel)]="password" />
      </div>
      <div class="line">
        <!-- la imagen SVG del captcha, hecha por NUESTRO servidor (véase el ejemplo 22) -->
        @if (captcha(); as c) {
          <img [src]="captchaImage(c)" alt="captcha" />
        }
        <ion-input label="captcha" labelPlacement="floating" autocorrect="off" autocapitalize="off"
          [(ngModel)]="captchaAnswer" (keyup.enter)="logIn()" />
        <ion-button fill="clear" aria-label="Log in" (click)="logIn()">
          <ion-icon slot="icon-only" name="log-in-outline" />
        </ion-button>
      </div>
      @if (error(); as message) {
        <ion-text color="danger"><div class="error">{{ message }}</div></ion-text>
      }
    }
  </ion-card-content>
</ion-card>

El formulario del Ejemplo 23, reducido a una barra y reescrito con el servicio [Api]. El componente emite el evento [userChange] cada vez que cambia el usuario con sesión iniciada, incluido el inicio.

  • línea 37 (.ts): el servicio [Api], obtenido por inyección (el [provider] de [Flutter]);
  • línea 41 (.ts): [output<User | null>()]: un evento que el componente emite a su padre (ejemplo 11), que se suscribe a él mediante [(userChange)="..."];
  • líneas 55–58 (.ts): un cambio de usuario: lo conservamos y notificamos al padre ([emit]);
  • líneas 66–77 (.ts): al iniciar, ¿quién ha iniciado sesión? [await this.api.get<User>('/auth/me')]: una sola línea. Cualquier error significa “nadie”: entonces se carga un CAPTCHA; si eso también falla, el servidor no responde. [catch] sin variable: el error en sí no se usa;
  • líneas 79–95 (.ts): el proceso de inicio de sesión, en pocas líneas: los errores aparecen como [ApiError], y se muestra el mensaje (“401 LOGIN.ERROR”: el Ejemplo 25 explicará la clave);
  • líneas 7–12 (html): con sesión iniciada: el usuario y su rol, y el botón “Cerrar sesión”;
  • líneas 13–31 (HTML): el formulario, distribuido en dos líneas ([display: flex]); presionar Enter en el campo del CAPTCHA envía el formulario ([(keyup.enter)], línea 24); el botón solo tiene un ícono y su nombre para los lectores de pantalla ([aria-label]).

9.3.5. La capa de acceso a la API

// =========================================================================
// src/app/ex24-api-layer/rdvmedecins.ts - la capa de acceso a la API
// -------------------------------------------------------------------------
// Un método por ruta de la API, tipado. Las pantallas no conocen ni las
// direcciones, ni el cliente HTTP, ni el formato JSON: llaman a
// métodos que devuelven objetos tipados (Person, Schedule...).
// Es el equivalente del lado del cliente de la capa DAO del lado del servidor: si la API
// cambia (una dirección, un nombre de campo), solo se modifica este archivo.
// Las guías de arquitectura llaman a esta capa un "repositorio".
// =========================================================================

import { HttpParams } from '@angular/common/http';
import { inject, Injectable } from '@angular/core';
import { Api } from '../common/api';
import { Schedule, Person } from '../common/types';

@Injectable({ providedIn: 'root' })
export class RdvMedecins {
  private readonly api = inject(Api);

  getDoctors(): Promise<Person[]> {
    return this.api.get<Person[]>('/doctors');
  }

  getClients(): Promise<Person[]> {
    return this.api.get<Person[]>('/clients');
  }

  // HttpParams construye "doctorId=1&day=2030-01-15", codificando lo necesario
  getSchedule(doctorId: number, day: string): Promise<Schedule> {
    const params = new HttpParams().set('doctorId', doctorId).set('day', day);
    return this.api.get<Schedule>(`/schedule?${params.toString()}`);
  }

  // clientId?: un parámetro opcional. ...(condition && object): la
  // propiedad clientId solo se coloca en el cuerpo si se proporciona clientId
  async book(day: string, slotId: number, clientId?: number | null): Promise<void> {
    await this.api.post('/appointments', { day, slotId, ...(clientId != null && { clientId }) });
  }

  async cancelAppointment(appointmentId: number): Promise<void> {
    await this.api.delete(`/appointments/${appointmentId}`);
  }
}

Un método por ruta de la API, con tipos. Las pantallas desconocen las direcciones, el cliente HTTP o el formato JSON: llaman a métodos que devuelven objetos tipados. Si la API cambia (una dirección, el nombre de un campo), solo se modifica este archivo. Las guías de arquitectura llaman a esta capa un “repositorio”.

  • Línea 19: la capa se apoya en el servicio [Api], que obtiene mediante inyección: [Angular] ensambla las capas por sí mismo, mientras que el [main] del cliente [Flutter] las creaba una por una ([RdvMedecins(api)]);
  • línea 31: [HttpParams] genera la cadena “doctorId=1&day=2030-01-15” codificando los datos necesarios;
  • línea 38: [clientId] solo se coloca en el cuerpo si se proporciona. [...(condition && object)]: si la condición es falsa, [false] se “expande”, lo que no agrega nada; de lo contrario, se expande el objeto [{ clientId }] (forma abreviada de [{ clientId: clientId }]). Era [?clientId] en [Dart] 3.8. [clientId != null] (con [!=] y no [!==]) excluye tanto [null] como [undefined].

9.3.6. El modelo de vista

// =========================================================================
// src/app/ex24-api-layer/schedule-model.ts - el "view model" de la pantalla
// -------------------------------------------------------------------------
// Las guías de arquitectura recomiendan separar:
//   - la VISTA: la plantilla y su clase, que muestran y transmiten las
//     acciones del usuario;
//   - el VIEW MODEL (ViewModel): un servicio que contiene el estado de
//     la pantalla (el médico elegido, el día, la agenda recibida...) en
//     SEÑALES, las acciones (elegir, reservar, cancelar), y que llama a la
//     capa de acceso a la API.
// La vista ya no tiene ninguna lógica: es sencilla de leer; el view model
// no tiene plantilla: es sencillo de probar.
// Lo proporciona la PÁGINA (providers: [ScheduleModel]): nace y muere
// con ella.
//
// También hace lo que no queremos reescribir en cada pantalla:
//   - un CACHÉ: la agenda de cada (médico, día) ya leída se conserva; al volver
//     a ella se muestra de inmediato, mientras se lee de nuevo en segundo plano;
//   - las respuestas OBSOLETAS se ignoran (véase el ejemplo 19).
// =========================================================================

import { computed, inject, Injectable, signal } from '@angular/core';
import { ApiError } from '../common/api-error';
import { Schedule, ScheduleSlot, timeRange, Person, User } from '../common/types';
import { RdvMedecins } from './rdvmedecins';

// una fecha -> "2026-10-07" (el día LOCAL; toISOString daría el día en Greenwich)
export function formatDay(d: Date): string {
  const twoDigits = (n: number) => String(n).padStart(2, '0');
  return `${d.getFullYear()}-${twoDigits(d.getMonth() + 1)}-${twoDigits(d.getDate())}`;
}

// mañana: el día de hoy, más uno
function tomorrow(): Date {
  const d = new Date();
  d.setDate(d.getDate() + 1);
  return d;
}

export interface Message {
  success: boolean;
  text: string;
}

@Injectable()
export class ScheduleModel {
  private readonly rdvmedecins = inject(RdvMedecins);

  // ==== el estado ====
  readonly user = signal<User | null>(null);
  readonly doctors = signal<Person[]>([]);
  readonly clients = signal<Person[]>([]);
  readonly doctorId = signal<number | null>(null);
  readonly day = signal(formatDay(tomorrow()));
  readonly clientId = signal<number | null>(null);
  readonly schedule = signal<Schedule | null>(null);
  readonly loading = signal(false);
  readonly message = signal<Message | null>(null);

  private readonly cache = new Map<string, Schedule>();
  private readNumber = 0;

  // ==== los valores calculados ====
  readonly loggedIn = computed(() => this.user() !== null);
  readonly isManager = computed(() => this.loggedIn() && this.user()?.role !== 'USER');

  // ==== las acciones ====
  async changeUser(u: User | null): Promise<void> {
    this.user.set(u);
    this.doctors.set([]);
    this.clients.set([]);
    this.schedule.set(null);
    this.doctorId.set(null);
    this.message.set(null);
    this.cache.clear(); // los derechos han cambiado: se olvida todo
    if (u === null) return;
    this.doctors.set(await this.rdvmedecins.getDoctors());
    // un USUARIO recibiría 403
    if (this.isManager()) this.clients.set(await this.rdvmedecins.getClients());
  }

  chooseDoctor(id: number): void {
    this.doctorId.set(id);
    this.message.set(null);
    this.readSchedule();
  }

  chooseDay(day: string): void {
    this.day.set(day);
    this.message.set(null);
    this.readSchedule();
  }

  chooseClient(id: number | null): void {
    this.clientId.set(id);
  }

  book(c: ScheduleSlot): Promise<void> {
    return this.act(
      () => this.rdvmedecins.book(this.day(), c.id, this.isManager() ? this.clientId() : null),
      `Slot ${timeRange(c)} booked.`,
    );
  }

  cancel(c: ScheduleSlot): Promise<void> {
    return this.act(() => this.rdvmedecins.cancelAppointment(c.appointmentId!), `Appointment of ${timeRange(c)} cancelled.`);
  }

  // una acción, y luego SIEMPRE una nueva lectura de la agenda: el SERVIDOR es la referencia
  private async act(action: () => Promise<void>, success: string): Promise<void> {
    try {
      await action();
      this.message.set({ success: true, text: success });
    } catch (e) {
      this.message.set({ success: false, text: e instanceof ApiError ? e.message : String(e) });
    }
    await this.readSchedule();
  }

  private async readSchedule(): Promise<void> {
    const id = this.doctorId();
    if (id === null) return;
    const key = `${id}/${this.day()}`;
    const number = ++this.readNumber;
    // primero el caché (o nada), luego la lectura
    this.schedule.set(this.cache.get(key) ?? null);
    this.loading.set(true);
    try {
      const read = await this.rdvmedecins.getSchedule(id, this.day());
      if (number !== this.readNumber) return; // se ha iniciado una lectura más reciente
      this.cache.set(key, read);
      this.schedule.set(read);
    } catch (e) {
      if (number !== this.readNumber) return;
      this.schedule.set(null);
      this.message.set({ success: false, text: e instanceof ApiError ? e.message : String(e) });
    }
    this.loading.set(false);
  }
}

Las guías de arquitectura recomiendan separar la vista (la plantilla y su clase, que muestran y transmiten las acciones del usuario) y el modelo de vista (un servicio que contiene el estado de la pantalla y sus acciones, y que llama a la capa de acceso a la API). La vista ya no contiene ninguna lógica; el modelo de vista no tiene plantilla: puede probarse sin pantalla.

  • Líneas 28–38: el día en el formato del servidor (“2026-10-07”) y el día siguiente. No usamos [toISOString()], que devolvería el día en la hora del meridiano de Greenwich: a las 12:30 a. m. en París, todavía es el día anterior;
  • línea 45: [@Injectable()], sin [providedIn]: el servicio no se provee a toda la aplicación, sino por la página que lo declara en sus [providers] (vea la pantalla). Se crea y se destruye junto con esa página;
  • líneas 50–58: el estado de la pantalla, representado mediante signals;
  • líneas 60–61: una caché: se almacena la agenda de cada (médico, día) que ya se leyó; al volver a ella, se muestra de inmediato mientras se vuelve a leer. Y el número de la última lectura, para ignorar las respuestas obsoletas (vea el ejemplo 19). Esto, en pocas líneas, es lo que hace la biblioteca [TanStack Query] del curso de [React];
  • líneas 64–65: valores calculados ([computed]): ¿sesión iniciada? ¿administrador (ADMIN o DOCTOR)?
  • líneas 68–80: un nuevo usuario: se ignora todo (los permisos cambiaron), luego se leen los médicos y, para ADMIN y DOCTOR, los clientes (un USER recibiría un 403);
  • Líneas 98–107: reservar, cancelar. El [!] de [c.appointmentId!] (línea 106) le indica al compilador que el valor no es [null]: el botón “Cancelar” solo se muestra en ese caso;
  • líneas 110–118: una acción, SIEMPRE seguida de una nueva lectura de la agenda: los datos del servidor tienen prioridad;
  • líneas 120–139: lectura de la agenda: primero la caché, o nada (línea 126), luego la respuesta del servidor, a menos que se haya iniciado una lectura más reciente entretanto (línea 130).

9.3.7. La pantalla

// =========================================================================
// src/app/ex24-api-layer/ex24.page.ts - una agenda, con la capa de acceso a la API
// -------------------------------------------------------------------------
// Inicie sesión (barra superior), elija un médico y un día:
// se muestra la agenda. ADMIN y DOCTOR pueden reservar para un paciente y
// cancelar; un paciente (martin...) reserva para sí mismo. Cada acción
// termina con una nueva lectura de la agenda.
// Tres capas, de abajo hacia arriba:
//   Api (common/api.ts)                  las solicitudes HTTP, los errores;
//   RdvMedecins (rdvmedecins.ts)         un método tipado por ruta de la API;
//   ScheduleModel (schedule-model.ts)    el estado y las acciones de la pantalla;
// y la vista (esta clase y su plantilla), que solo muestra el modelo.
// =========================================================================

import { Component, inject } from '@angular/core';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonChip, IonContent, IonDatetime, IonHeader,
  IonIcon, IonItem, IonLabel, IonList, IonModal, IonProgressBar, IonSelect, IonSelectOption, IonText, IonTitle,
  IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { addCircleOutline, calendarOutline, closeCircleOutline } from 'ionicons/icons';
import { LoginBar } from '../common/login-bar';
import { timeRange, fullName } from '../common/types';
import { ScheduleModel } from './schedule-model';

@Component({
  selector: 'app-ex24',
  imports: [
    IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonSelect, IonSelectOption, IonButton,
    IonIcon, IonModal, IonDatetime, IonCard, IonCardContent, IonProgressBar, IonText, IonList, IonItem, IonLabel,
    IonChip, LoginBar,
  ],
  templateUrl: './ex24.page.html',
  // el view model lo proporciona la PÁGINA: una instancia por página, destruida con ella
  providers: [ScheduleModel],
  styles: `
    .day { display: flex; align-items: center; }
    ion-modal.calendar { --width: fit-content; --height: fit-content; --border-radius: 8px; }
    .message { margin: 8px 0; }
    .success { --background: #e8f5e9; --color: #333; }
    .failure { --background: #ffebee; --color: #333; }
    .schedule-title { font-weight: bold; font-size: 14px; margin: 8px 0; }
    .time-range { flex: 0 0 90px; font-size: 13px; }
    .free { --background: #c8e6c9; }
    .mine { --background: #c5cae9; }
    .other { --background: #e0e0e0; }
    ion-item ion-icon { font-size: 26px; }
  `,
})
export class Ex24Page {
  readonly model = inject(ScheduleModel);
  readonly timeRange = timeRange;
  readonly fullName = fullName;

  constructor() {
    addIcons({ calendarOutline, addCircleOutline, closeCircleOutline });
  }

  // ion-datetime devuelve "2026-10-07" (presentation="date"), o un arreglo si
  // se pueden elegir varias fechas: solo conservamos una cadena
  chooseDay(value: string | string[] | null | undefined): void {
    if (typeof value === 'string') this.model.chooseDay(value.substring(0, 10));
  }
}
<!-- ======================================================================
     ex24.page.html - la vista: solo muestra el view model
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>Example 24 - an API access layer</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <!-- la barra de inicio de sesión notifica al view model -->
  <app-login-bar (userChange)="model.changeUser($event)" />

  @if (model.loggedIn()) {
    <ion-select placeholder="-- choose a doctor --" interface="popover" class="doctor-choice" aria-label="doctor"
      [value]="model.doctorId()" (ionChange)="model.chooseDoctor($event.detail.value)">
      @for (m of model.doctors(); track m.id) {
        <ion-select-option [value]="m.id">{{ fullName(m) }}</ion-select-option>
      }
    </ion-select>

    <div class="day">
      Day: {{ model.day() }}
      <ion-button id="calendar24" fill="clear" aria-label="choose the day">
        <ion-icon slot="icon-only" name="calendar-outline" />
      </ion-button>
    </div>
    <ion-modal class="calendar" trigger="calendar24">
      <ng-template>
        <ion-datetime presentation="date" locale="en-US" [firstDayOfWeek]="1" [showDefaultButtons]="true"
          doneText="OK" cancelText="Cancel" [value]="model.day()" (ionChange)="chooseDay($event.detail.value)" />
      </ng-template>
    </ion-modal>

    <!-- ADMIN y DOCTOR: el paciente para quien se reserva -->
    @if (model.isManager()) {
      <ion-select interface="popover" class="patient-choice" aria-label="patient" [value]="model.clientId()"
        (ionChange)="model.chooseClient($event.detail.value)">
        <ion-select-option [value]="null">-- patient to book --</ion-select-option>
        @for (c of model.clients(); track c.id) {
          <ion-select-option [value]="c.id">{{ fullName(c) }}</ion-select-option>
        }
      </ion-select>
    }

    @if (model.message(); as message) {
      <ion-card class="message" [class.success]="message.success" [class.failure]="!message.success">
        <ion-card-content>{{ message.text }}</ion-card-content>
      </ion-card>
    }
    @if (model.loading()) {
      <ion-progress-bar type="indeterminate" />
    }

    @if (model.schedule(); as schedule) {
      <!-- info: la clave enviada por el servidor cuando un paciente ya tiene una cita próxima -->
      @if (schedule.info) {
        <ion-text color="primary"><div>{{ schedule.info }}</div></ion-text>
      }
      <div class="schedule-title">Schedule of {{ schedule.day }} - {{ fullName(schedule.doctor) }}</div>
      <ion-list lines="none">
        <!-- una fila por franja: el rango horario, el ocupante, el botón permitido -->
        @for (c of schedule.slots; track c.id) {
          <ion-item>
            <ion-label class="time-range">{{ timeRange(c) }}</ion-label>
            @if (c.free) {
              <ion-chip class="free">Free</ion-chip>
            } @else {
              <ion-chip [class.mine]="c.mine" [class.other]="!c.mine">
                {{ c.patient ? fullName(c.patient) : 'Booked' }}
              </ion-chip>
            }
            <!-- los botones siguen los derechos calculados por el servidor -->
            @if (c.bookable) {
              <ion-button slot="end" fill="clear" color="success" aria-label="Book" (click)="model.book(c)">
                <ion-icon slot="icon-only" name="add-circle-outline" />
              </ion-button>
            } @else if (c.appointmentId !== null) {
              <ion-button slot="end" fill="clear" color="danger" aria-label="Cancel" (click)="model.cancel(c)">
                <ion-icon slot="icon-only" name="close-circle-outline" />
              </ion-button>
            }
          </ion-item>
        }
      </ion-list>
    }
  }
</ion-content>
  • línea 36 (.ts): [providers: [ScheduleModel]]: la página provee el modelo de vista a sí misma y a los componentes que contiene. Las otras dos capas ([Api], [RdvMedecins]) se proveen a toda la aplicación ([providedIn: 'root']);
  • línea 52 (.ts): la vista obtiene el modelo de vista; no tiene ningún otro estado;
  • líneas 53–54 (.ts): las funciones de formato, hechas accesibles a la plantilla (una plantilla solo puede ver los miembros de su clase);
  • líneas 62–64 (.ts): [ion-datetime] devuelve la fecha seleccionada (“2026-10-07”), o un arreglo si se pudieran seleccionar varias fechas: solo se conserva una cadena;
  • línea 16 (html): la barra de inicio de sesión notifica al modelo de vista; [$event] es el valor devuelto, ya sea el usuario o [null];
  • líneas 19–24 (HTML): la selección del médico: un [<ion-select>] cuya lista se abre en una ventana emergente ([interface="popover"]); su valor se lee del modelo de vista, y cada selección ([ionChange]) activa una acción del modelo de vista;
  • líneas 26–37 (HTML): el día y un calendario en una ventana modal (como en el Ejemplo 21): [ion-datetime], en inglés estadounidense, con la semana comenzando el lunes; sus botones OK y Cancelar ([showDefaultButtons]) cierran la ventana, y OK confirma el día ([ionChange]);
  • líneas 40–48 (HTML): para ADMIN y DOCTOR, el paciente para quien se hace la cita;
  • líneas 50–57 (html): el mensaje de la última acción (verde o rojo: [[class.success]] agrega la clase CSS cuando la condición es verdadera) y la barra de progreso durante la lectura;
  • líneas 61–63 (html): [info], la clave enviada por el servidor cuando el paciente ya tiene una cita próxima. Se muestra tal cual: el Ejemplo 25 enseñará a decodificar las claves;
  • líneas 67–88 (HTML): una línea por franja horaria: la hora, un [<ion-chip>] (una “viñeta”) con la etiqueta “Libre” o el nombre del paciente (en índigo si es la cita del paciente con sesión iniciada), y el botón correspondiente. Los botones siguen los permisos calculados por el servidor ([bookable], [appointmentId]): la pantalla no toma ninguna decisión.

Con la sesión iniciada como [admin], la agenda de la Sra. PELISSIER para el día siguiente; una franja horaria reservada para el Sr. Jean MARTIN; con la sesión iniciada como [martin] (rol USER), la misma agenda:

El paciente [martin] ve su cita (en índigo, con el botón de cancelar); la clave [SCHEDULE.ALREADY_BOOKED_INFO] indica que ya tiene una cita próxima: no hay otras franjas horarias disponibles para reservar. La cita de otro paciente aparecería como “Reservado”, sin nombre: el servidor no se lo envía al usuario.

9.4. Ejemplo 25: errores devueltos por el servidor

9.4.1. Los diccionarios

{
  "FORM": {
    "TITLE_ADD": "Ajouter un client",
    "TITLE_EDIT": "Modifier un client",
    "TITLE": "Titre",
    "FIRSTNAME": "Prénom",
    "LASTNAME": "Nom",
    "LOGIN": "Login",
    "PASSWORD": "Mot de passe",
    "SAVE": "Enregistrer",
    "CANCEL": "Annuler",
    "EDIT": "Modifier",
    "DELETE": "Supprimer",
    "DELETE_CONFIRM": "Supprimer le client {{name}}, son compte et ses rendez-vous ?",
    "ADDED": "Le client {{name}} a été ajouté (login : {{login}}).",
    "UPDATED": "Le client {{name}} a été modifié.",
    "DELETED": "Le client {{name}} a été supprimé.",
    "ADMIN_ONLY": "Connectez-vous avec le compte admin : seul le rôle ADMIN gère les clients.",
    "PAGE_TITLE": "Exemple 25 - les erreurs du serveur",
    "NEW": "Nouveau client"
  },
  "ERRORS": {
    "INVALID_FORM": "Le formulaire contient des erreurs.",
    "INVALID_TITLE": "Choisissez un titre dans la liste.",
    "FIRSTNAME_REQUIRED": "Le prénom est obligatoire.",
    "FIRSTNAME_TOO_LONG": "Le prénom ne doit pas dépasser 20 caractères.",
    "LASTNAME_REQUIRED": "Le nom est obligatoire.",
    "LASTNAME_TOO_LONG": "Le nom ne doit pas dépasser 20 caractères.",
    "INVALID_LOGIN": "30 caractères au plus : lettres minuscules non accentuées, chiffres, point, tiret, souligné.",
    "PASSWORD_TOO_LONG": "Le mot de passe ne doit pas dépasser 72 caractères.",
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "PATIENT_ALREADY_EXISTS": "Un client portant ce prénom et ce nom existe déjà.",
    "PATIENT_NOT_FOUND": "Ce client n'existe pas (ou plus).",
    "CONCURRENT_UPDATE": "Cette fiche a été modifiée entre-temps par un autre utilisateur. Rechargez-la avant de recommencer.",
    "FORBIDDEN": "Votre rôle ne vous permet pas cette action.",
    "AUTH_REQUIRED": "Connectez-vous d'abord.",
    "SESSION_EXPIRED": "Votre session a expiré : reconnectez-vous.",
    "SERVER_UNREACHABLE": "Le serveur ne répond pas.",
    "SERVER_ERROR": "Une erreur inattendue s'est produite.",
    "WRONG_CAPTCHA": "Les caractères recopiés ne correspondent pas à l'image."
  }
}

Los mensajes de error del servidor son claves (“ERRORS.LASTNAME_REQUIRED”): el diccionario las traduce. Estos son los diccionarios del ejemplo [Flutter], sin cambios; el diccionario en inglés, [ex25-en.json], tiene las mismas claves. Al igual que los del Ejemplo 21, se encuentran en la carpeta [public/i18n/] del proyecto, que se entrega tal cual con la aplicación.

9.4.2. La pantalla

// =========================================================================
// src/app/ex25-server-errors/ex25.page.ts - mostrar los errores del SERVIDOR
// -------------------------------------------------------------------------
// La gestión de los clientes (cuenta admin). Este formulario NO hace
// DELIBERADAMENTE ninguna validación en el teléfono: todo se envía al
// servidor, que responde, en caso de rechazo, con un error JSON (convertido en
// un ApiError por common/api.ts):
//
//   400 { key: 'ERRORS.INVALID_FORM', fields: { lastName: 'ERRORS.LASTNAME_REQUIRED' } }
//   409 { key: 'ERRORS.PATIENT_ALREADY_EXISTS', fields: { firstName: ..., lastName: ... } }
//   409 { key: 'ERRORS.CONCURRENT_UPDATE' }         (bloqueo optimista)
//
// El error de CADA campo (ApiError.fields) se entrega a su control de
// formulario (setErrors): ion-input lo muestra bajo el campo (errorText).
// Su mensaje es la CLAVE enviada por el servidor, que la pantalla traduce
// (diccionarios del ejemplo 21). Modificar un campo borra su error.
// Pruebe: un nombre vacío, un título "Dr", un homónimo (Alice DURAND), un
// login ya en uso (martin), el mismo registro modificado en dos dispositivos...
// =========================================================================

import { Component, inject, signal } from '@angular/core';
import { NonNullableFormBuilder, ReactiveFormsModule } from '@angular/forms';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonCardHeader, IonCardTitle, IonContent, IonHeader,
  IonIcon, IonInput, IonItem, IonLabel, IonList, IonNote, IonPopover, IonSelect, IonSelectOption, IonText, IonTitle,
  IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { createOutline, languageOutline, trashOutline } from 'ionicons/icons';
import { Api } from '../common/api';
import { LoginBar } from '../common/login-bar';
import { ApiError, Texts } from '../common/api-error';
import { fullName, Person, User } from '../common/types';
import { injectConfirmation } from '../ex16-confirmation/confirmation';
import { languages, Translations } from '../ex21-i18n/translations';
import { Command } from '../ex23-login/command';

// los campos del formulario, y un mensaje por traducir (una clave y sus parámetros)
type Field = 'title' | 'firstName' | 'lastName' | 'login' | 'password';
interface Success {
  key: string;
  params: Texts;
}

@Component({
  selector: 'app-ex25',
  imports: [
    ReactiveFormsModule, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonButton, IonIcon, IonPopover,
    IonContent, IonList, IonItem, IonLabel, IonCard, IonCardHeader, IonCardTitle, IonCardContent, IonSelect,
    IonSelectOption, IonInput, IonText, IonNote, LoginBar,
  ],
  templateUrl: './ex25.page.html',
  // las traducciones de la página, con los diccionarios ex25-fr.json y ex25-en.json
  providers: [{ provide: Translations, useFactory: () => new Translations('ex25') }],
  styles: `
    .warning { --background: #fff8e1; --color: #333; }
    .message { margin-top: 12px; }
    .status { font-size: 12px; }
  `,
})
export class Ex25Page {
  private readonly api = inject(Api);
  private readonly confirm = injectConfirmation();
  readonly tr = inject(Translations);
  readonly languages = languages;
  readonly titles = ['Mr', 'Mme', 'Melle', 'Dr']; // "Dr": el servidor lo rechazará
  readonly fullName = fullName;

  readonly user = signal<User | null>(null);
  readonly clients = signal<Person[]>([]);

  // el formulario: SIN reglas de validación, todo lo verifica el servidor
  readonly form = inject(NonNullableFormBuilder).group({
    title: ['Mr'],
    firstName: [''],
    lastName: [''],
    login: [''],
    password: [''],
  });
  // null: creación; en caso contrario, el id del cliente modificado y la versión leída con su registro
  readonly editedId = signal<number | null>(null);
  private version = 0;

  // el mensaje general del último error, y el de un éxito
  readonly pageError = signal<ApiError | null>(null);
  readonly success = signal<Success | null>(null);
  // el envío al servidor: un Command (ejemplo 23), que indica si está en curso
  readonly sending = new Command();

  constructor() {
    addIcons({ languageOutline, createOutline, trashOutline });
    this.tr.start();
  }

  isAdmin(): boolean {
    return this.user()?.role === 'ADMIN';
  }

  private async reload(): Promise<void> {
    this.clients.set(await this.api.get<Person[]>('/clients'));
  }

  async onUserChange(u: User | null): Promise<void> {
    this.user.set(u);
    this.clients.set([]);
    if (u?.role === 'ADMIN') await this.reload();
  }

  // el error de un campo, devuelto por el servidor, traducido ('': sin error)
  fieldError(field: Field): string {
    const key = this.form.controls[field].errors?.['server'];
    return typeof key === 'string' ? this.tr.t(key) : '';
  }

  private clearMessages(): void {
    this.pageError.set(null);
    this.success.set(null);
  }

  newForm(): void {
    this.editedId.set(null);
    this.version = 0;
    // reset: los valores iniciales, y ya ningún error
    this.form.reset();
    this.clearMessages();
  }

  edit(c: Person): void {
    this.editedId.set(c.id);
    // la VERSIÓN leída con el registro se reenvía con la modificación: si alguien
    // ha modificado el registro mientras tanto, el servidor responderá 409 CONCURRENT_UPDATE
    this.version = c.version;
    this.form.reset({ title: c.title, firstName: c.firstName, lastName: c.lastName, login: c.login ?? '', password: '' });
    this.clearMessages();
  }

  // el botón "Guardar"
  submit(): void {
    this.sending.execute(() => this.save());
  }

  private async save(): Promise<void> {
    this.clearMessages();
    const input = { ...this.form.getRawValue(), version: this.version };
    const id = this.editedId();
    try {
      const client =
        id === null
          ? await this.api.post<Person>('/clients', input)
          : await this.api.put<Person>(`/clients/${id}`, input);
      this.newForm(); // formulario vaciado, mensajes borrados...
      // ... excepto este
      this.success.set({
        key: id === null ? 'FORM.ADDED' : 'FORM.UPDATED',
        params: { name: `${client.firstName} ${client.lastName}`, login: client.login ?? '' },
      });
      await this.reload();
    } catch (e) {
      if (!(e instanceof ApiError)) throw e;
      this.pageError.set(e); // el mensaje general
      // el error de cada campo: se entrega a su control, que
      // pasa a ser inválido (ng-invalid); markAsTouched lo marca como "tocado"
      // (ng-touched): Ionic muestra entonces su errorText
      for (const [field, key] of Object.entries(e.fields)) {
        const control = this.form.get(field);
        control?.setErrors({ server: key });
        control?.markAsTouched();
      }
    }
  }

  async remove(c: Person): Promise<void> {
    const name = `${c.firstName} ${c.lastName}`;
    if (!(await this.confirm(this.tr.t('FORM.DELETE_CONFIRM', { name })))) return;
    this.clearMessages();
    try {
      await this.api.delete(`/clients/${c.id}`);
      this.success.set({ key: 'FORM.DELETED', params: { name } });
    } catch (e) {
      if (e instanceof ApiError) this.pageError.set(e);
    }
    await this.reload();
  }
}
<!-- ======================================================================
     ex25.page.html - la gestión de los clientes, y los errores del servidor
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>{{ tr.t('FORM.PAGE_TITLE') }}</ion-title>
    <!-- el idioma: un menú, en una ventana emergente (ion-popover) -->
    <ion-buttons slot="end">
      <ion-button id="language25" aria-label="language">
        <ion-icon slot="icon-only" name="language-outline" />
      </ion-button>
    </ion-buttons>
    <ion-popover trigger="language25" [dismissOnSelect]="true">
      <ng-template>
        <ion-list>
          @for (l of languages; track l) {
            <ion-item [button]="true" (click)="tr.changeLanguage(l)">{{ l.toUpperCase() }}</ion-item>
          }
        </ion-list>
      </ng-template>
    </ion-popover>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <app-login-bar (userChange)="onUserChange($event)" />

  @if (user() !== null && !isAdmin()) {
    <ion-card class="warning">
      <ion-card-content>{{ tr.t('FORM.ADMIN_ONLY') }}</ion-card-content>
    </ion-card>
  }

  @if (isAdmin()) {
    <ion-list>
      @for (c of clients(); track c.id) {
        <ion-item>
          <ion-label>
            {{ fullName(c) }}
            <p>{{ c.login }}</p>
          </ion-label>
          <ion-button slot="end" fill="clear" color="dark" [attr.aria-label]="tr.t('FORM.EDIT')"
            (click)="edit(c)">
            <ion-icon slot="icon-only" name="create-outline" />
          </ion-button>
          <ion-button slot="end" fill="clear" color="danger" [attr.aria-label]="tr.t('FORM.DELETE')"
            (click)="remove(c)">
            <ion-icon slot="icon-only" name="trash-outline" />
          </ion-button>
        </ion-item>
      }
    </ion-list>

    <ion-card>
      <ion-card-header>
        <ion-card-title>{{ tr.t(editedId() === null ? 'FORM.TITLE_ADD' : 'FORM.TITLE_EDIT') }}</ion-card-title>
      </ion-card-header>
      <ion-card-content>
        <!-- no (ngSubmit): el botón Guardar llama a submit() -->
        <form [formGroup]="form">
          <!-- errorText: el error del campo devuelto por el servidor, traducido. Ionic
               lo muestra cuando el control es inválido (ion-invalid) y está tocado (ion-touched) -->
          <ion-select [label]="tr.t('FORM.TITLE')" labelPlacement="floating" interface="popover"
            formControlName="title" [errorText]="fieldError('title')">
            @for (t of titles; track t) {
              <ion-select-option [value]="t">{{ t }}</ion-select-option>
            }
          </ion-select>
          <ion-input [label]="tr.t('FORM.FIRSTNAME')" labelPlacement="floating" formControlName="firstName"
            [errorText]="fieldError('firstName')" />
          <ion-input [label]="tr.t('FORM.LASTNAME')" labelPlacement="floating" formControlName="lastName"
            [errorText]="fieldError('lastName')" />
          <ion-input [label]="tr.t('FORM.LOGIN')" labelPlacement="floating" formControlName="login"
            [errorText]="fieldError('login')" />
          <ion-input [label]="tr.t('FORM.PASSWORD')" labelPlacement="floating" type="password"
            formControlName="password" [errorText]="fieldError('password')" />
        </form>

        <ion-button class="ion-margin-top" shape="round" [disabled]="sending.running()" (click)="submit()">
          {{ tr.t('FORM.SAVE') }}
        </ion-button>
        <ion-button class="ion-margin-top" shape="round" fill="outline" (click)="newForm()">
          {{ tr.t('FORM.CANCEL') }}
        </ion-button>

        @if (success(); as s) {
          <div class="message"><ion-text color="success">{{ tr.t(s.key, s.params) }}</ion-text></div>
        }
        <!-- el mensaje general, y el estado HTTP, para entender -->
        @if (pageError(); as e) {
          <div class="message">
            <ion-text color="danger">{{ tr.t(e.key, e.params) }}</ion-text>
            <ion-note class="status"> ({{ e.message }})</ion-note>
          </div>
        }
      </ion-card-content>
    </ion-card>
  }
</ion-content>

Gestión de clientes (cuenta de administrador). Este formulario no realiza ninguna validación en el teléfono: todo se envía al servidor, que responde, en caso de rechazo, con un JSON de error, convertido en [ApiError] por el servicio [Api].

  • Líneas 34–36 (.ts): la página reutiliza tres herramientas de los ejemplos anteriores, importándolas desde sus respectivas carpetas: la confirmación del Ejemplo 16, las traducciones del Ejemplo 21 y el comando del Ejemplo 23 (el cliente [Flutter] hacía lo mismo). La clase [Translations] del Ejemplo 21 se escribió con este fin: no es un servicio singleton, sino una clase configurada por el prefijo de sus diccionarios. La línea 54 crea una instancia para esta página, con los diccionarios [ex25-fr.json] y [ex25-en.json]. ¿Por qué no moverla a [common/]? Allí encajaría en una aplicación; en este curso, cada ejemplo se lee en orden, y el Ejemplo 21 sigue siendo el que la presenta;
  • línea 63 (.ts): la función de confirmación del Ejemplo 16 ([AlertController]);
  • línea 66 (.ts): un título “Dr”, que el servidor rechazará: vea [ERRORS.INVALID_TITLE];
  • líneas 73–79 (.ts): un formulario reactivo (Ejemplo 08), SIN ninguna regla de validación;
  • líneas 81–82 (.ts): el cliente modificado ([null]: una nueva creación) y la versión recuperada junto con su registro;
  • líneas 85–88 (.ts): el mensaje general del último error, el mensaje de éxito (una clave y sus parámetros, traducidos para mostrarlos: siguen un cambio de idioma) y el envío, un [Command] (ejemplo 23);
  • líneas 110–113 (.ts): el mensaje de error de un campo. El error se almacena en la lógica de validación del campo con el nombre [server] (vea más abajo); su valor es la clave enviada por el servidor, que se traduce;
  • líneas 120–126 (.ts): un nuevo cliente: [form.reset()] restablece los valores predeterminados (el formulario es “no nulo”, ejemplo 08) y borra todos los errores;
  • líneas 128–135 (.ts): editar un cliente: el formulario recibe el registro del cliente. La versión leída del registro se actualiza con el cambio: si alguien modificó el registro mientras tanto, el servidor responderá con un 409 [CONCURRENT_UPDATE] (el bloqueo optimista);
  • líneas 142–170 (.ts): guardar: [POST /api/clients] (crear) o [PUT /api/clients/:id] (actualizar), con los valores del formulario y la versión (línea 144). Si tiene éxito, se borra el formulario y se muestra un mensaje de éxito (líneas 151–156). Si se rechaza, [ApiError] muestra el mensaje general (línea 160) y el error de cada campo (líneas 164–168):
  • [control.setErrors({ server: key })] devuelve un error en la validación del campo: el campo pasa a ser inválido (clase [ng-invalid]);
  • [control.markAsTouched()] lo marca como “tocado” (clase [ng-touched]), como si se hubiera salido de él;
  • [Ionic] copia estas dos clases—[ion-invalid] y [ion-touched]—al campo (ejemplo 07): entonces muestra, debajo del campo, el texto de su [errorText], y lo resalta en rojo;
  • y editar el campo borra el error sin una sola línea de código: con cada pulsación de tecla, [Angular] vuelve a validar el campo según sus reglas… y no tiene ninguna. El error establecido manualmente desaparece. Esto era un [onChanged] que había que escribir para cada campo en el cliente [Flutter];
  • líneas 172–183 (.ts): eliminación, tras la confirmación (el mensaje de confirmación se traduce, con el nombre del cliente como parámetro);
  • líneas 11–25 (html): idioma: un botón en la barra superior que abre un [<ion-popover>] (una ventana emergente asociada al botón, cuyo [id] se indica mediante [trigger]); [dismissOnSelect] la cierra en la primera selección. Este era el [PopupMenuButton] de [Flutter];
  • líneas 32–36 (html): un usuario con sesión iniciada que no es ADMIN: una advertencia;
  • líneas 38–56 (html): la lista de clientes, con sus botones “Editar” y “Eliminar”;
  • líneas 64–81 (HTML): el formulario. Cada campo está enlazado a su control ([formControlName]); sus etiquetas están traducidas; [[errorText]] recibe el error del servidor, traducido (líneas 67–68: [<ion-select>] también tiene un [errorText]). El formulario no tiene un [(ngSubmit)]: el botón “Guardar” llama al comando (líneas 83–85);
  • líneas 90–99 (HTML): el mensaje de éxito y el mensaje de error general, traducidos; para mayor claridad, el estado HTTP y la clave se muestran en letra pequeña.

Un formulario vacío; un homónimo (“Alice DURAND”); lo mismo, en francés:

Cambiar el idioma vuelve a traducir toda la pantalla, incluidos los errores ya mostrados: la pantalla almacena las claves enviadas por el servidor, no el texto, y las traduce cada vez que se muestra la pantalla. Pruebe también: un título “Dr”, un nombre de usuario que ya existe ([martin]), un nombre de usuario no válido (“Jean M”) o el mismo registro editado en dos dispositivos (o en dos pestañas del navegador, o en la aplicación y con [curl]).

El principio es el mismo que en todos los formularios del caso de estudio: las reglas residen en un SOLO lugar, el servidor; la aplicación muestra sus respuestas en el idioma del usuario. Por supuesto, nada impide validar también los campos en el teléfono (ejemplo 08) para responder más rápido al usuario; sin embargo, el servidor debe volver a validarlo todo, y su veredicto es definitivo.

Al comparar los dos clientes, se aprecia hasta qué punto [Ionic] se apoya en el navegador: el cliente HTTP devuelve directamente objetos [JavaScript] (JSON es el lenguaje nativo de [JavaScript]), la cookie del token se transmite sin una sola línea de código, y una solicitud se puede cancelar. A cambio, [TypeScript] no valida el formato de las respuestas en tiempo de ejecución, lo que el filtrado de [Dart] hacía de forma natural. El cliente [Angular] de [RdvMedecins] (curso [Angular]) se escribe exactamente como estos ejemplos: el mismo [HttpClient], los mismos servicios, los mismos formularios reactivos; solo difieren los componentes de visualización, con los de [Ionic] imitando los de un teléfono [Android].