expo-api-routes

Quando Usar Rotas de API

Use rotas de API quando precisar de:

• Segredos do lado do servidor — Chaves de API, credenciais de banco de dados ou tokens que nunca devem chegar ao cliente
• Operações de banco de dados — Consultas diretas ao banco de dados que não devem ser expostas
• Proxies de API de terceiros — Ocultar chaves de API ao chamar serviços externos (OpenAI, Stripe, etc.)
• Validação do lado do servidor — Validar dados antes de gravar no banco de dados
• Endpoints de Webhook — Receber callbacks de serviços como Stripe ou GitHub
• Limitação de taxa (Rate limiting) — Controlar o acesso no nível do servidor
• Computação pesada — Descarregar processamento que seria lento em dispositivos móveis

Quando NÃO Usar Rotas de API

Evite rotas de API quando:

• Os dados já são públicos — Use fetch direto para APIs públicas em vez disso
• Nenhum segredo é necessário — Dados estáticos ou operações seguras para o cliente
• Atualizações em tempo real são necessárias — Use WebSockets ou serviços como Supabase Realtime
• CRUD simples — Considere Firebase, Supabase ou Convex para backends gerenciados
• Upload de arquivos — Use uploads diretos para armazenamento (URLs pré-assinadas do S3, Cloudflare R2)
• Apenas autenticação — Use Clerk, Auth0 ou Firebase Auth em vez disso

Estrutura de Arquivos

As rotas de API ficam no diretório app com o sufixo +api.ts:

app/
  api/
    hello+api.ts          → GET /api/hello
    users+api.ts          → /api/users
    users/[id]+api.ts     → /api/users/:id
  (tabs)/
    index.tsx

Rota de API Básica

// app/api/hello+api.ts
export function GET(request: Request) {
  return Response.json({ message: "Hello from Expo!" });
}

Métodos HTTP

Exporte funções nomeadas para cada método HTTP:

// app/api/items+api.ts
export function GET(request: Request) {
  return Response.json({ items: [] });
}

export async function POST(request: Request) {
  const body = await request.json();
  return Response.json({ created: body }, { status: 201 });
}

export async function PUT(request: Request) {
  const body = await request.json();
  return Response.json({ updated: body });
}

export async function DELETE(request: Request) {
  return new Response(null, { status: 204 });
}

Rotas Dinâmicas

// app/api/users/[id]+api.ts
export function GET(request: Request, { id }: { id: string }) {
  return Response.json({ userId: id });
}

Tratamento de Requisições

Parâmetros de Consulta (Query Parameters)

export function GET(request: Request) {
  const url = new URL(request.url);
  const page = url.searchParams.get("page") ?? "1";
  const limit = url.searchParams.get("limit") ?? "10";

  return Response.json({ page, limit });
}

Cabeçalhos (Headers)

export function GET(request: Request) {
  const auth = request.headers.get("Authorization");

  if (!auth) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  return Response.json({ authenticated: true });
}

Corpo JSON

export async function POST(request: Request) {
  const { email, password } = await request.json();

  if (!email || !password) {
    return Response.json({ error: "Missing fields" }, { status: 400 });
  }

  return Response.json({ success: true });
}

Variáveis de Ambiente

Use process.env para segredos do lado do servidor:

// app/api/ai+api.ts
export async function POST(request: Request) {
  const { prompt } = await request.json();

  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    },
    body: JSON.stringify({
      model: "gpt-4",
      messages: [{ role: "user", content: prompt }],
    }),
  });

  const data = await response.json();
  return Response.json(data);
}

Defina variáveis de ambiente:

• Local: Crie o arquivo .env (nunca envie para o Git)
• Hospedagem EAS: Use eas env:create ou o painel do Expo

Cabeçalhos CORS

Adicione CORS para clientes web:

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization",
};

export function OPTIONS() {
  return new Response(null, { headers: corsHeaders });
}

export function GET() {
  return Response.json({ data: "value" }, { headers: corsHeaders });
}

Tratamento de Erros

export async function POST(request: Request) {
  try {
    const body = await request.json();
    // Processar...
    return Response.json({ success: true });
  } catch (error) {
    console.error("Erro na API:", error);

…