Frontend: datos, APIs y APIs de Backstage

Objetivos del capítulo

Usar useApi y fetchApi con tipos TypeScript.
Consumir el catalog desde tu plugin.
Manejar errores con ErrorApi, notificaciones e identidad.

ApisRegistry: el bus del frontend

El backend tiene coreServices; el frontend tiene ApisRegistry. Es el mismo concepto: una pieza pide lo que necesita y el shell se lo inyecta. La sala del restaurante tiene su propio sistema de pedidos: cada camarero pide al jefe de sala y el jefe le pasa lo que necesita.

Backstage expone APIs de sistema a través de refs:

:code:`catalogApiRef` — acceso al catalog.
:code:`errorApiRef` — notificación de errores.
:code:`identityApiRef` — usuario autenticado.
:code:`notificationApiRef` — toasts.
:code:`fetchApiRef` — fetch configurado con auth headers.

ApisRegistry como bus de servicios

Failed to generate image: Could not find the 'mmdc' executable in PATH; add it to the PATH or specify its location using the 'mmdc' document attribute
flowchart LR
  Comp[Component] --> Hook[useApi]
  Hook --> Reg[ApisRegistry]
  Reg --> Catalog[catalogApiRef]
  Reg --> Error[errorApiRef]
  Reg --> Identity[identityApiRef]
  Reg --> Notif[notificationApiRef]

Consumir el catalog con useApi

Un hook que consulta el catalog de Sazón Foods:

Unresolved directive in chapters/cap-09-frontend-datos-y-apis.adoc - include::../../chapters/chapter-09-frontend-data/src/hooks.ts[tag=useapi-hook]

Lo que acabas de hacer

:code:`useApi(catalogApiRef)` resuelve el API por ref.
:code:`getEntities({ filter })` consulta entidades con un filtro estructurado.
:code:`errorApi.post(err)` muestra el error en la UI estándar (no console.error).

Filtros de catalog

El parámetro filter es por kind, namespace, spec, etc. Ejemplos:

:code:`{ kind: 'Component' }` — todos los componentes.
:code:`{ kind: 'Component', 'spec.system': 'sazon-restaurant' }` — los del System.
:code:`{ kind: 'API', 'spec.type': 'openapi' }` — APIs declaradas.

Combina con :code:`fields:` para reducir el payload.

Consumir tu propio backend

Para llamar a un endpoint custom (como /api/sazon/status del :cap-06), usa fetchApiRef o el fetch global según el caso:

Unresolved directive in chapters/cap-09-frontend-datos-y-apis.adoc - include::../../chapters/chapter-09-frontend-data/src/hooks.ts[tag=catalog-api-consumer]

Proxy en desarrollo

:code:`fetch('/api/…')` desde el navegador solo funciona si el frontend tiene un proxy al backend en app-config.yaml:

proxy:
  '/api/sazon': http://localhost:7007/api/sazon

En producción, el frontend se sirve detrás del mismo dominio que el backend o un proxy inverso.

Manejo de errores

Tres reglas:

Nunca console.error y ya. Usa errorApi.post(err) para que aparezca la UI de error.
Loading y error states son obligatorios en cualquier fetch. Muestra un <Progress /> mientras loading y un <EmptyState /> si la lista está vacía.
401/403 se manejan vía el ErrorApi. Backstage los trata especialmente: el 401 te redirige a login.

Example 9. Receta del capítulo

Importa los refs (catalogApiRef, errorApiRef) que necesites.
Usa useApi(ref) para resolverlos en componentes.
Para datos de catálogo, prefiere catalogApi.getEntities() sobre fetch manual.
Para endpoints custom, configura el proxy y usa fetchApiRef.
Maneja loading, error y empty state en cada componente que hace fetch.

Resumen

ApisRegistry expone servicios del shell a los plugins.
useApi(ref) los resuelve en componentes.
catalogApiRef da acceso al catalog con filtros estructurados.
errorApi.post(err) muestra errores en la UI estándar.

Glosario del capítulo

ApisRegistry: Bus de APIs del shell, equivalente frontend de coreServices.
ref: Objeto ApiRef<T> que identifica un API por su tipo T.
useApi: Hook que resuelve un ref en su implementación inyectada.
fetchApiRef: Ref al fetch configurado con auth headers del shell.
proxy: Config de app-config.yaml que redirige paths del dev server al backend.

Próximo capítulo

Componentes, tablas y UX consistente —composición con Material UI y los componentes de @backstage/core-components.