Diagramas de secuencia Mermaid para llamadas de API y servicios

Los diagramas de secuencia explican el orden de las interacciones. Son preferibles a un diagrama de flujo cuando la pregunta es “¿quién envía qué a quién y cuándo?”. Se usan para llamadas de navegador a API, autenticación, webhooks, colas y reintentos entre servicios.

Declara participantes con nombres útiles

sequenceDiagram
  actor Usuario
  participant Web as Aplicación web
  participant API as API de pedidos
  participant DB as Base de datos

  Usuario->>Web: Enviar pedido
  Web->>API: POST /orders
  API->>DB: Insertar pedido
  DB-->>API: ID del pedido
  API-->>Web: 201 Created
  Web-->>Usuario: Mostrar confirmación

Los alias mantienen breves los mensajes y muestran etiquetas claras. Usa actores para roles humanos y participantes para software. Ordénalos para que el camino principal sea fácil de seguir.

Distingue llamadas y respuestas

Las flechas continuas suelen representar solicitudes y las discontinuas respuestas. Es una convención visual, no una garantía de sincronía. Si importa distinguir trabajo bloqueante y asíncrono, indícalo en la etiqueta o en el texto adjunto.

Muestra alternativas sin duplicar diagramas

sequenceDiagram
  Client->>API: GET /profile
  alt token válido
    API-->>Client: 200 Perfil
  else token caducado
    API-->>Client: 401 Unauthorized
  end

Usa alt para resultados alternativos, opt para una rama opcional y loop para repeticiones. Describe la condición, no un detalle de implementación.

Representa tiempo y responsabilidad con honestidad

El eje vertical no es una escala temporal precisa. Si la latencia importa, añade mediciones a los mensajes o usa otro gráfico. Modela interacciones entre límites relevantes, no cada llamada a una función interna.

Pega el ejemplo en el editor de diagramas Mermaid y sustituye los participantes de uno en uno. Exporta SVG para conservar nitidez a cualquier tamaño.