Padrões de Integração de API Frontend

Visão Geral

Esta habilidade oferece padrões prontos para produção para integrar aplicações frontend com APIs de backend.

A maioria dos problemas de frontend não é causada por APIs difíceis de chamar, mas sim pelo manuseio incorreto de comportamento assíncrono — levando a condições de corrida, dados desatualizados, requisições duplicadas e má experiência do usuário.

Esta habilidade foca em correção, resiliência e experiência do usuário, não apenas em fazer as chamadas de API funcionarem.

Quando Usar Esta Habilidade

• Conectar aplicações frontend (React, React Native, Vue, etc.) a APIs de backend
• Integrar endpoints de ML/IA (/predict, /recommend)
• Lidar com dados assíncronos na UI
• Corrigir dados desatualizados, flickering na UI ou requisições duplicadas
• Projetar camadas de API frontend escaláveis

Padrões Principais

1. Camada de API (Separação de Responsabilidades)

Centralize a lógica da API e normalize os erros.

export class ApiError extends Error {
  constructor(message, status, payload = null) {
    super(message);
    this.name = "ApiError";
    this.status = status;
    this.payload = payload;
  }
}

export const apiClient = async (url, options = {}) => {
  const res = await fetch(url, {
    headers: { "Content-Type": "application/json" },
    ...options,
  });

  if (!res.ok) {
    let payload = null;
    try {
      payload = await res.json();
    } catch (_) {}

    throw new ApiError(
      payload?.message || "Request failed",
      res.status,
      payload
    );
  }

  // handle empty responses safely (e.g. 204 No Content)
  if (res.status === 204) return null;

  const text = await res.text();
  return text ? JSON.parse(text) : null;
};

2. Gerenciamento de Estado Seguro contra Condições de Corrida

Evite que respostas desatualizadas sobrescrevam dados recentes.

useEffect(() => {
  let cancelled = false;

  const load = async () => {
    try {
      setLoading(true);
      setError(null);

      const result = await getUser();

      if (!cancelled) setData(result);
    } catch (err) {
      if (!cancelled) setError(err.message);
    } finally {
      if (!cancelled) setLoading(false);
    }
  };

  load();

  return () => {
    cancelled = true;
  };
}, []);

Use uma flag de cancelamento para lógica assíncrona que não seja fetch. Para requisições de rede, prefira AbortController.

3. Cancelamento de Requisição (AbortController)

Cancele requisições em andamento para evitar vazamentos de memória e atualizações desatualizadas.

useEffect(() => {
  const controller = new AbortController();

  const load = async () => {
    try {
      const data = await getUser({ signal: controller.signal });
      setData(data);
    } catch (err) {
      if (err.name === "AbortError") return;
      setError(err.message);
    }
  };

  load();
  return () => controller.abort();
}, [userId]);

4. Tentativa com Backoff Exponencial

Tente novamente apenas operações explicitamente seguras para repetição e falhas transitórias classificadas. O padrão executa uma tentativa. Não classifique exceções arbitrárias de programação ou parsing como erros de rede. Respeite o Retry-After do provedor e um prazo total no adaptador real; não ative este backoff simples para respostas de limite de taxa. O exemplo de predição POST intencionalmente não ativa tentativas, a menos que o contrato do backend garanta independentemente a segurança de repetição.

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

const fetchWithBackoff = async (fn, retries = 3, delay = 300, replaySafe = false) => {
  try {
    return await fn();
  } catch (err) {
    const isAbort = err.name === "AbortError";
    const isHttpError = typeof err.status === "number";
    const isNetworkFailure = err.code === "NETWORK_ERROR";
    const isRetryable = replaySafe && !isAbort &&
      (isNetworkFailure || (isHttpError && err.status >= 500));

    if (retries <= 0 || !isRetryable) throw err;

    const nextDelay = delay * 2 + Math.random() * 100;
    await sleep(nextDelay);

    return fetchWithBackoff(fn, retries - 1, nextDelay, replaySafe);
  }
};

5. Chamadas de API Debounced

Evite chamadas excessivas de API (por exemplo, campos de busca).

const useDebounce = (value, delay = 400) => {
  const [debounced, setDebounced] = useState(value);

  useEffect(() => {
    const t = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(t);
  }, [value, delay]);

  return debounced;
};

6. Deduplicação de Requisições

Evite chamadas de API duplicadas entre componentes.

const inFlight = new Map();


…