Cómo hospedar una API

Una API que funciona en localhost:3000 todavía no está publicada. Para que una app, un sitio u otro servidor pueda llamarla, el proceso debe estar activo todo el tiempo, en una dirección accesible desde internet e, idealmente, con HTTPS.

Esta guía lleva una API sencilla desde tu computadora hasta producción, en Node.js y en Python. Las ideas valen para cualquier lenguaje: escuchar en la interfaz correcta, leer el puerto del entorno, mantener los secretos fuera del código y exponer una ruta que demuestre que el servicio está vivo.

¿Qué necesitas antes de empezar?#

• Una API que ya corre en local y responde al menos una ruta.
• Un archivo de dependencias (package.json o requirements.txt).
• Un lugar donde ejecutarla: un VPS, un servidor propio o una plataforma de hosting. La elección cambia quién mantiene el sistema operativo, no lo que la API debe hacer.
• Los secretos (claves, URL de la base de datos) fuera del código, en variables de entorno. Mira qué son las variables de entorno.

¿Cómo preparar la API para producción?#

Tres ajustes resuelven la mayoría de los problemas de publicación. La metodología Twelve-Factor App describe el primero y el tercero (puerto y configuración):

1. Puerto desde el entorno. Quien sabe qué puerto está libre es el entorno, no tu código. Lee process.env.PORT (o os.environ) y deja un valor por defecto solo para desarrollo.
2. Escuchar en 0.0.0.0. En 127.0.0.1 (localhost), la API solo acepta conexiones de la misma máquina. En un servidor o contenedor, eso la hace parecer caída.
3. Configuración fuera del código. La URL de la base de datos, las claves y los flags viven en variables de entorno, nunca en el repositorio.

Agrega también una ruta de salud, como GET /health, que devuelva 200 sin tocar la base de datos. Con ella, tú, un monitor externo o un balanceador saben si el proceso responde.

¿Cómo publicar una API en Node.js?#

Con una versión reciente de Node.js instalada, crea el proyecto e instala 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) => {
  // En Express 5, un error lanzado aquí llega solo al manejador de errores
  res.json({ id: req.params.id, name: "Ada" });
});

// Manejador de errores: siempre al final
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; // en Express 5, errores como EADDRINUSE llegan aquí
  console.log(`API escuchando en el puerto ${port}`);
});

Dos diferencias entre Express 5 y 4: los handlers async que fallan se envían al manejador de errores sin .catch(next), y el callback de app.listen recibe el error como primer argumento.

Ejecútalo con PORT=3000 node index.js.

¿Cómo publicar una API en Python?#

Con FastAPI, instala la versión con los extras estándar (incluye 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"}

En producción, ejecútalo sin --reload: la documentación de FastAPI reserva esa opción para desarrollo, porque consume más recursos y es menos estable.

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

main:app significa "el objeto app del archivo main.py". fastapi[standard] también instala el comando fastapi, que la documentación recomienda: fastapi run main.py --port "${PORT:-8000}" ya escucha en 0.0.0.0. Para ejecutar más de un proceso, consulta la página de workers de Uvicorn en la documentación de FastAPI.

¿Cómo saber si la API está en línea?#

Prueba desde fuera del servidor, no desde dentro:

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

Esperas el estado 200 (la primera línea muestra HTTP/2 200 o HTTP/1.1 200 OK, según el servidor) y el JSON {"status":"ok"}. Para un POST con cuerpo:

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

Si solo funciona en tu computadora, el problema está entre el cliente y el proceso: red, puerto, DNS o HTTPS. Para usar un dominio, mira cómo apuntar un dominio a tu aplicación. El ciclo de enviar el código e iniciar el proceso se explica en qué es el deploy.

¿Cuáles son los errores más comunes?#

La conexión es rechazada o expira. Casi siempre la API escucha en 127.0.0.1 o en un puerto distinto del expuesto. Revisa el host (0.0.0.0) y el puerto leído del entorno.

El puerto ya está en uso. Node muestra:

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

Otro proceso ya usa el puerto. Ciérralo o cambia PORT.

La API se cae justo al iniciar. Revisa los logs: normalmente falta una dependencia en el servidor o una variable de entorno (un undefined convertido en URL de base de datos).

El navegador bloquea la llamada con un error de CORS. El servidor respondió, pero sin las cabeceras que autorizan el origen de tu sitio. Configura CORS en la API (el paquete cors en Express, CORSMiddleware en FastAPI) con orígenes exactos en lugar de permitir todo.

Funciona con HTTP y falla con HTTPS. Una página servida por HTTPS no puede llamar a una API en HTTP (contenido mixto). Publica la API detrás de HTTPS.

La API es lenta o se reinicia sola. Puede faltarle memoria. Mide el uso real en vez de adivinar; mira cómo dimensionar RAM y CPU.

¿Qué más cuidar en una API pública?#

• Autenticación: exige clave o token en las rutas que modifican datos.
• Límite de peticiones: sin rate limit, un cliente con un bug puede tumbar el servicio.
• Logs: registra método, ruta y estado, sin guardar contraseñas ni tokens.
• Versionado: prefija las rutas con /v1 para poder evolucionar sin romper a los clientes.

Cómo hacerlo en Square Cloud#

Los tres ajustes de esta guía son lo que Square Cloud espera de una API: la plataforma define la variable PORT, la API escucha en 0.0.0.0 en ese puerto y el tráfico le llega por HTTPS. Subes el proyecto como ZIP en el panel, con la CLI, desde GitHub o con la extensión de VS Code, y el formulario de deploy detecta el archivo principal. El archivo squarecloud.app es opcional: el panel lo genera en el deploy.

El ejemplo en Express arranca directo desde index.js. FastAPI necesita un comando de inicio, porque ejecutar main.py solo crea el objeto app y nunca abre un servidor. En el campo de comando de inicio del formulario, usa uvicorn main:app --host 0.0.0.0 --port $PORT.

Todos los planes, desde el Hobby (R$12,49 al mes), le dan a la aplicación web un subdominio *.squareweb.app con TLS automático, así que la ruta de salud responde apenas termina el deploy: curl -i https://mi-api.squareweb.app/health. Si la API se cae al iniciar, los logs en tiempo real muestran la salida de npm install o de pip install -r requirements.txt y el error. Las variables de entorno se definen en el panel y valen desde el siguiente reinicio, sin rebuild. El reinicio automático viene activado en el deploy desde el panel y levanta de nuevo un proceso que terminó con error; quedarse sin memoria, en cambio, detiene la aplicación hasta que aumentes su RAM y la inicies otra vez.

El dominio propio y el hosting de bases de datos empiezan en Standard. El dominio sigue en tu registrador, donde creas los registros DNS que muestra el panel. No hay autoscaling: para crecer, aumentas la RAM o repartes el dominio entre varias aplicaciones con load balancing. Consulta runtimes, límites y planes en hosting de APIs y compara precios en planes.