Diagramas de sequência Mermaid para chamadas de API e serviços

Diagramas de sequência explicam a ordem das interações. São melhores que fluxogramas quando a pergunta é “quem envia o quê para quem e quando?”. Casos comuns incluem chamadas do navegador à API, autenticação, webhooks, filas e novas tentativas entre serviços.

Declare participantes com nomes úteis

sequenceDiagram
  actor User as Usuário
  participant Web as Aplicação web
  participant API as API de pedidos
  participant DB as Banco de dados
  User->>Web: Enviar pedido
  Web->>API: POST /orders
  API->>DB: Inserir pedido
  DB-->>API: ID do pedido
  API-->>Web: 201 Created
  Web-->>User: Mostrar confirmação

Aliases mantêm mensagens compactas e exibem nomes claros. Use atores para pessoas e participantes para software. Ordene-os de forma que o caminho principal seja fácil de acompanhar.

Diferencie chamadas e respostas

Setas contínuas costumam representar solicitações e pontilhadas, respostas. Isso é uma convenção, não garantia de sincronismo. Se a diferença entre trabalho bloqueante e assíncrono importar, declare-a no rótulo ou texto.

Mostre alternativas sem duplicar diagramas

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

Use alt para alternativas, opt para ramo opcional e loop para repetição. O rótulo deve descrever a condição, não uma função interna.

Seja honesto sobre tempo e responsabilidade

O eixo vertical não é uma escala precisa. Se latência importa, informe medições nas mensagens. Modele interações entre limites relevantes, não cada chamada interna.

Teste o exemplo no editor de diagramas Mermaid e exporte SVG para preservar a nitidez em diferentes larguras.