Axios: o que é, requisições HTTP e fundamentos do trabalho com API

O que é Axios?

Axios é uma biblioteca JavaScript projetada para fazer requisições HTTP a partir do navegador e do ambiente Node.js. Ela é construída sobre XMLHttpRequest no navegador e o módulo http no Node.js, fornecendo uma API unificada para ambas as plataformas.

A principal vantagem do Axios sobre o fetch nativo é o tratamento automático de JSON, suporte a interceptadores e tratamento de erros mais conveniente. Ao contrário do fetch, o Axios não requer duas chamadas .then para obter o corpo JSON da resposta e lança exceções automaticamente em erros HTTP (4xx, 5xx).

A biblioteca suporta todos os principais métodos HTTP: GET, POST, PUT, DELETE, PATCH e HEAD. Pode ser usada tanto em projetos simples quanto em grandes aplicações empresariais com centenas de milhares de requisições diárias.

Características principais do Axios

• Promise API — todas as operações retornam uma Promise, simplificando o código assíncrono
• Suporte TypeScript — tipagem completa para todos os métodos e configurações
• Interceptadores — middleware para processar requisições e respostas
• Transformação — transformação automática de dados na entrada e saída

Arquitetura do Axios e princípio de funcionamento

A arquitetura do Axios é baseada no conceito de adaptadores. A biblioteca abstrai a camada de transporte: usa XMLHttpRequest no navegador e o módulo http ou https no Node.js. Isso fornece uma interface única independentemente do ambiente de execução.

Cada requisição passa por uma cadeia de interceptadores que podem modificar a configuração da requisição ou resposta. Após os interceptadores, a requisição é passada para o adaptador, que realiza a chamada HTTP real. A resposta então passa pelos interceptadores de resposta antes de chegar ao código da aplicação.

Ciclo de vida de uma requisição Axios

1. Criação de configuração — método, URL, cabeçalhos, corpo da requisição
2. Interceptador de requisição — modificação da configuração, adição de tokens
3. Chamada HTTP — execução através do adaptador do navegador ou Node.js
4. Interceptador de resposta — transformação da resposta, tratamento de erros
5. Retorno do resultado — Promise é resolvida com dados ou rejeitada

Principais recursos do Axios

Axios inclui muitos recursos embutidos que o tornam uma escolha conveniente para trabalhar com HTTP em aplicativos móveis e web. Vamos explorar os principais.

Transformação automática de dados

Ao enviar uma requisição, o Axios transforma automaticamente um objeto JavaScript em uma string JSON usando JSON.stringify. Ao receber uma resposta, a biblioteca converte JSON de volta em um objeto. Isso poupa o desenvolvedor da serialização e desserialização manual de dados.

Proteção CSRF

No ambiente do navegador, o Axios adiciona automaticamente os cabeçalhos XSRF-TOKEN dos cookies, protegendo a aplicação contra falsificação de requisição entre sites. Para isso, basta configurar o servidor para enviar o token em um cookie chamado XSRF-TOKEN.

Timeouts e cancelamento de requisições

A biblioteca suporta definir um timeout através do parâmetro timeout e cancelamento de requisição via AbortController. Isso é especialmente importante em aplicativos móveis com conexões instáveis, onde requisições travadas consomem bateria e dados.

Instalação e configuração do Axios

A instalação do Axios é feita através de qualquer gerenciador de pacotes. A biblioteca está disponível no registro npm e pode ser usada tanto em projetos Node.js quanto em projetos de navegador. Para TypeScript, os tipos estão incluídos no pacote principal — dependências adicionais não são necessárias.

Após a instalação, você pode criar uma instância com uma configuração básica: URL base, timeout padrão, cabeçalhos comuns. Isso evita repetir os mesmos parâmetros em cada requisição e gerencia as configurações do cliente HTTP de forma centralizada.

# Instalar via npm
npm install axios

# Instalar via yarn
yarn add axios

# Instalar via pnpm
pnpm add axios

Criando uma instância com configuração

É recomendado criar uma instância separada de Axios para cada serviço API. Isso permite definir uma URL base, cabeçalhos padrão e timeout que serão aplicados a todas as requisições desta instância sem repeti-los em cada chamada.

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.example.com/v1',
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

Exemplos de código com Axios

Os exemplos de requisições mostram os principais padrões de uso do Axios. Todos os exemplos usam a sintaxe async/await, que torna o código assíncrono mais legível em comparação com cadeias de .then().

Requisição GET com parâmetros

Para obter dados do servidor, utiliza-se o método axios.get. Os parâmetros da requisição são passados através do objeto params, que é automaticamente transformado em uma query string. A resposta contém os dados no campo data, o status em status e os cabeçalhos em headers.

interface User {
  id: number;
  name: string;
  email: string;
}

async function getUsers() {
  try {
    const response = await api.get<User[]>('/users', {
      params: { page: 1, limit: 10 }
    });
    return response.data;
  } catch (error) {
    console.error('Erro ao carregar usuários', error);
    throw error;
  }
}

Requisição POST com corpo

Para enviar dados ao servidor, utiliza-se axios.post. O segundo argumento é um objeto com dados, que o Axios serializa automaticamente para JSON. O Content-Type é definido como application/json por padrão.

interface CreateUserDto {
  name: string;
  email: string;
  role: string;
}

async function createUser(data: CreateUserDto) {
  const response = await api.post<User>('/users', data);
  return response.data;
}

Interceptadores

Os interceptadores são funções middleware que executam para cada requisição ou resposta. Eles permitem adicionar tokens de autorização, registrar requisições e tratar erros centralizadamente. Um interceptador de requisição adiciona o cabeçalho Authorization com um token obtido do armazenamento.

// Interceptador de requisição — adiciona token de autorização
api.interceptors.request.use(
  (config) => {
    const token = getToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

// Interceptador de resposta — lida com erros 401
api.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      redirectToLogin();
    }
    return Promise.reject(error);
  }
);

Tratamento de erros no Axios

O tratamento de erros no Axios é baseado no mecanismo de exceções. Ao contrário do fetch, o Axios captura automaticamente erros HTTP (4xx, 5xx) e os passa para o bloco catch. O objeto de erro contém informações sobre a resposta do servidor, a requisição e o contexto de execução.

É importante distinguir três tipos de erros: erro de resposta do servidor (response), erro de requisição (request) e erro de configuração (config). O primeiro ocorre quando a chamada HTTP é executada com sucesso mas retorna um código de erro, o segundo quando não há resposta do servidor, e o terceiro quando a configuração da requisição está incorreta.

import axios, { AxiosError } from 'axios';

async function safeRequest() {
  try {
    return await api.get('/data');
  } catch (error) {
    if (error instanceof AxiosError) {
      if (error.response) {
        console.warn('Erro de resposta', error.response.status);
      } else if (error.request) {
        console.warn('Sem resposta do servidor');
      } else {
        console.warn('Erro de configuração');
      }
    }
  }
}

Comparação do Axios com Fetch API

A comparação do Axios com a Fetch API nativa ajuda a entender quando cada tecnologia é adequada. Fetch é uma API embutida no navegador que não requer instalação. Axios é uma biblioteca de terceiros com recursos adicionais. Para requisições simples, fetch é suficiente; para aplicações complexas com interceptadores e tratamento centralizado de erros, Axios é mais conveniente.

Fetch não considera erros HTTP (4xx, 5xx) como exceções — é preciso verificar response.ok. Fetch requer duas chamadas .then() para obter JSON: response.json() então retorna uma Promise com os dados. Axios faz isso automaticamente. Fetch não suporta progresso de upload de arquivos sem polyfills adicionais. Axios tem onUploadProgress e onDownloadProgress embutidos.

No Node.js, Fetch está disponível desde a versão 18 como um recurso experimental, enquanto Axios funciona de forma estável desde o Node.js 10. Para projetos que suportam versões antigas do Node.js, a escolha é claramente a favor do Axios. Para projetos modernos de navegador sem processamento complexo de requisições, fetch pode ser suficiente.