Como hospedar uma API

Uma API que funciona em localhost:3000 ainda não está publicada. Para que um aplicativo, um site ou outro servidor consiga chamá-la, o processo precisa rodar o tempo todo, num endereço acessível pela internet e, de preferência, com HTTPS.

Este guia leva uma API simples do seu computador até a produção, em Node.js e em Python. As ideias valem para qualquer linguagem: escutar na interface certa, ler a porta do ambiente, guardar segredos fora do código e expor uma rota que prove que o serviço está vivo.

O que você precisa antes de começar?#

• Uma API que já roda localmente e responde a pelo menos uma rota.
• Um arquivo com a lista de dependências (package.json ou requirements.txt).
• Um lugar para rodar: uma VPS, um servidor próprio ou uma plataforma de hospedagem. A escolha muda quem cuida do sistema operacional, mas não o que a API precisa fazer.
• Os segredos (chaves, URL do banco) separados do código, em variáveis de ambiente. Veja o que são variáveis de ambiente.

Como preparar a API para produção?#

Três ajustes resolvem a maioria dos problemas de publicação. A metodologia Twelve-Factor App descreve o primeiro e o terceiro (porta e configuração):

1. Porta vinda do ambiente. Quem sabe qual porta está livre é o ambiente, não o código. Leia process.env.PORT (ou os.environ) e deixe um valor padrão só para desenvolvimento.
2. Escutar em 0.0.0.0. Em 127.0.0.1 (localhost), a API aceita só conexões da própria máquina. Num servidor ou container, isso a faz parecer "fora do ar".
3. Configuração fora do código. URL do banco, chaves e flags ficam em variáveis de ambiente, nunca no repositório.

Crie também uma rota de saúde, como GET /health, que devolve 200 sem tocar no banco. Com ela, você, um monitor externo ou um balanceador sabem se o processo responde.

Como subir uma API em Node.js?#

Com uma versão recente do Node.js instalada, crie o projeto e instale o Express 5:

npm init -y
npm install express@5

index.js:

const express = require("express");

const app = express();
const port = process.env.PORT || 3000;

app.use(express.json());

app.get("/health", (req, res) => {
  res.json({ status: "ok" });
});

app.get("/users/:id", async (req, res) => {
  // No Express 5, um erro lançado aqui chega ao tratador de erros sozinho
  res.json({ id: req.params.id, name: "Ada" });
});

// Tratador de erros: sempre por último
app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({ error: "internal_error" });
});

app.listen(port, "0.0.0.0", (error) => {
  if (error) throw error; // no Express 5, erros como EADDRINUSE chegam aqui
  console.log(`API ouvindo na porta ${port}`);
});

Duas diferenças do Express 5 em relação ao 4: handlers async que rejeitam são encaminhados ao tratador de erros sem .catch(next), e o callback de app.listen recebe o erro como primeiro argumento.

Rode com PORT=3000 node index.js.

Como subir uma API em Python?#

Com FastAPI, instale a versão com os extras padrão (inclui o Uvicorn):

pip install "fastapi[standard]"

main.py:

from fastapi import FastAPI

app = FastAPI()


@app.get("/health")
def health():
    return {"status": "ok"}


@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"id": user_id, "name": "Ada"}

Em produção, rode sem --reload: a documentação do FastAPI reserva essa opção ao desenvolvimento, porque gasta mais recursos e é menos estável.

uvicorn main:app --host 0.0.0.0 --port "${PORT:-8000}"

main:app significa "o objeto app do arquivo main.py". O fastapi[standard] também instala o comando fastapi, que a documentação recomenda: fastapi run main.py --port "${PORT:-8000}" já escuta em 0.0.0.0. Para rodar mais de um processo, consulte a página de workers do Uvicorn na documentação do FastAPI.

Como saber se a API está no ar?#

Teste de fora do servidor, não de dentro dele:

curl -i https://api.seudominio.com/health

Você espera o status 200 (a primeira linha mostra HTTP/2 200 ou HTTP/1.1 200 OK, conforme o servidor) e o JSON {"status":"ok"}. Para um POST com corpo:

curl -i -X POST https://api.seudominio.com/items \
  -H "Content-Type: application/json" \
  -d '{"name":"teste"}'

Se só funciona no seu computador, o problema está entre o cliente e o processo: rede, porta, DNS ou HTTPS. Para usar um domínio, veja como apontar um domínio para sua aplicação. O ciclo de enviar o código e iniciar o processo está explicado em o que é deploy.

Quais são os erros mais comuns?#

A conexão é recusada ou dá timeout. Quase sempre a API escuta em 127.0.0.1 ou numa porta diferente da exposta. Confira o host (0.0.0.0) e a porta lida do ambiente.

A porta já está em uso. O Node mostra:

Error: listen EADDRINUSE: address already in use 0.0.0.0:3000

Outro processo já usa a porta. Encerre-o ou mude PORT.

A API cai logo depois de iniciar. Leia os logs: normalmente falta uma dependência no servidor ou uma variável de ambiente (um undefined virando URL do banco).

O navegador bloqueia a chamada com erro de CORS. O servidor respondeu, mas sem os cabeçalhos que autorizam a origem do seu site. Configure CORS na API (o pacote cors no Express, o CORSMiddleware no FastAPI) com as origens exatas, em vez de liberar tudo.

Funciona por HTTP e falha por HTTPS. Um site em HTTPS não pode chamar uma API em HTTP (conteúdo misto). Publique a API atrás de HTTPS.

A API é lenta ou reinicia sozinha. Pode ser falta de memória. Meça o uso real em vez de chutar; veja como dimensionar RAM e CPU.

O que mais cuidar numa API pública?#

• Autenticação: exija chave ou token em rotas que alteram dados.
• Limite de requisições: sem rate limit, um cliente com bug pode derrubar o serviço.
• Logs: registre método, rota e status, sem gravar senhas ou tokens.
• Versionamento: prefixe rotas com /v1 para poder evoluir sem quebrar clientes.

Como fazer isso na Square Cloud#

Os três ajustes deste guia são o que a Square Cloud espera de uma API: a plataforma define a variável PORT, a API escuta em 0.0.0.0 nessa porta e o tráfego chega a ela por HTTPS. Você envia o projeto por ZIP no painel, pela CLI, pelo GitHub ou pela extensão do VS Code, e o formulário de deploy detecta o arquivo principal. O arquivo squarecloud.app é opcional: o painel o gera no deploy.

O exemplo em Express sobe direto pelo index.js. O FastAPI precisa de um comando de início, porque executar o main.py só cria o objeto app e não abre nenhum servidor. No campo de comando de início do formulário, use uvicorn main:app --host 0.0.0.0 --port $PORT.

Todo plano, a partir do Hobby (R$ 12,49 por mês), dá à aplicação web um subdomínio *.squareweb.app com TLS automático, então a rota de saúde já responde logo após o deploy: curl -i https://minha-api.squareweb.app/health. Se a API cair ao iniciar, os logs em tempo real mostram a saída do npm install ou do pip install -r requirements.txt e o erro. As variáveis de ambiente ficam no painel e valem no próximo restart, sem rebuild. O reinício automático vem ligado no deploy pelo painel e traz de volta um processo que encerrou com erro; um estouro de memória, ao contrário, para a aplicação até você aumentar a RAM e iniciá-la de novo.

Domínio próprio e hospedagem de bancos começam no Standard. O domínio continua no seu registrador, onde você cria os registros DNS que o painel mostra. Não há autoscaling: para crescer, você aumenta a RAM ou divide o domínio entre várias aplicações com load balancing. Veja runtimes, limites e planos em hospedagem de APIs e compare os preços em planos.