Module 1: Setup and First API

Introducción al Módulo 1: Setup y Primera API

Next →

Descripción

Vas a construir tu primera API con FastAPI. En este módulo instalas el framework, configuras tu entorno de desarrollo, levantas un servidor y ves la documentación automática generarse sin escribir una sola línea extra. Es el primer paso del path Backend Python Developer y la base sobre la que construirás todo lo demás en esta guía.

FastAPI es el framework que empresas como Netflix, Uber y Microsoft usan para construir APIs de alto rendimiento. No es un framework más: genera documentación interactiva automáticamente, valida datos sin que tú escribas validadores, y su rendimiento es comparable a Node.js y Go. Al terminar este módulo, tendrás un servidor corriendo con hot reload y entenderás por qué FastAPI se ha convertido en el estándar para APIs en Python.

¿Dónde estamos en la guía?

Esta es la Guía #6 del path Backend Python Developer con FastAPI. Hasta aquí ya completaste:

  • ✅ Python Essentials (#1): Variables, funciones, clases, módulos, async/await
  • ✅ REST APIs & HTTP (#5): Verbos HTTP, status codes, headers, JSON, arquitectura REST

Ahora toca traducir todo ese conocimiento a un framework real. Sabes qué es un GET, sabes qué es un 200 OK, sabes escribir funciones en Python. En este módulo conectas las piezas: una función Python que responde a un GET y retorna JSON con status 200.

Guías completadas          Esta guía                  Siguientes
─────────────────          ──────────                 ──────────
#1 Python Essentials   →   #6 FastAPI Fundamentals    → #7 FastAPI Advanced
#5 REST & HTTP         →   (ESTÁS AQUÍ)               → #9 Authentication
                                                       → #11 Testing

Tu conocimiento previo aplicado

Cada concepto que aprendiste antes tiene una aplicación directa en FastAPI:

Guía anteriorConceptoAplicación en FastAPI
Python EssentialsFunciones con type hintsPath operation functions
Python EssentialsDiccionariosRespuestas JSON
Python EssentialsDecoradores@app.get(), @app.post()
Python Essentialsasync/awaitEndpoints asíncronos
Python Essentialspip y módulosInstalar FastAPI y dependencias
REST & HTTPVerbos GET, POST, PUT, DELETEDecoradores de FastAPI
REST & HTTPStatus codes (200, 404, 422)Respuestas HTTP automáticas
REST & HTTPJSON como formatoSerialización automática
REST & HTTPPath y query parametersParámetros en endpoints

No empiezas de cero — empiezas con herramientas que ya dominas.

La transición clave de este módulo:

Hasta ahora, usabas Python para scripts que se ejecutan y terminan. Con FastAPI, tu código Python se convierte en un servidor que escucha permanentemente, recibiendo y respondiendo requests HTTP. Es un cambio de paradigma: pasas de "ejecutar un programa" a "levantar un servicio."

# Antes (script): se ejecuta una vez y termina
result = calculate_something()
print(result)
# → Script termina

# Ahora (API): se levanta y espera requests indefinidamente
@app.get("/calculate")
def calculate():
    return {"result": calculate_something()}
# → Servidor escucha en puerto 8000, siempre disponible

Objetivo del módulo

Al completar este módulo serás capaz de:

  • ✅ Crear un proyecto FastAPI desde cero con estructura profesional
  • ✅ Instalar FastAPI y uvicorn en un entorno virtual aislado
  • ✅ Levantar un servidor con hot reload que se actualiza al guardar cambios
  • ✅ Crear endpoints GET que retornan JSON
  • ✅ Explorar la documentación interactiva automática en /docs y /redoc
  • ✅ Entender qué es una "path operation function" y cómo los decoradores conectan rutas con funciones

Prerequisitos

Para este módulo necesitas:

  • Python 3.9+ instalado y funcionando desde terminal
  • pip operativo (verificar con pip --version)
  • Un editor de código (VS Code recomendado, con extensión Python)
  • Terminal (la usarás constantemente para levantar el servidor)
  • Conocimiento de HTTP: Saber qué son GET, POST, status codes y JSON (Guía #5)
  • Conocimiento de Python: Funciones, decoradores básicos, tipo de datos (Guía #1)

Verificación rápida: Si puedes abrir terminal, escribir python --version y ver Python 3.9+, estás listo.

¿Qué pasa si no cumples algún prerequisito?

Prerequisito faltanteQué hacer
Python no instaladoDescarga desde python.org
Python < 3.9Actualiza con tu package manager o descarga nueva versión
pip no funcionaReinstala con python -m ensurepip --upgrade
No conoces HTTP/RESTCompleta la Guía #5 (REST APIs & HTTP Fundamentals) primero
No conoces PythonCompleta la Guía #1 (Python Essentials) primero

No saltes prerequisitos. Esta guía asume que sabes Python y HTTP. Si no los dominas, el contenido será confuso en lugar de productivo.

Roadmap del módulo

Este módulo tiene 5 cápsulas que siguen una progresión clara:

CápsulaTemaQué aprenderás
01Introducción (esta cápsula)Contexto, roadmap, qué construirás
02Instalación y setupVirtual environment, pip install, estructura de proyecto
03Primer endpoint y uvicornHello world, levantar servidor, hot reload, path operations
04Documentación automática/docs, /redoc, OpenAPI schema, personalización
05Proyecto: Hello World APIAPI completa con múltiples endpoints y estructura profesional

Flujo de aprendizaje

Primero configurarás tu entorno de desarrollo con un virtual environment dedicado y la estructura de carpetas que usarás en toda la guía (Cápsula 02). Después crearás tu primer endpoint y verás cómo uvicorn levanta tu servidor con hot reload — podrás modificar código y ver los cambios en tiempo real sin reiniciar nada (Cápsula 03). Luego explorarás una de las features más poderosas de FastAPI: la documentación automática interactiva que te permite probar tus endpoints directamente desde el navegador (Cápsula 04). Al final, integrarás todo en un mini-proyecto Hello World API con estructura profesional (Cápsula 05).

La progresión es directa: instalar → crear → explorar → construir.

Detalle por cápsula

Cápsula 02 — Instalación y setup: Crearás un virtual environment dedicado al proyecto, instalarás FastAPI y uvicorn, generarás un requirements.txt con las versiones exactas, y armarás la estructura de carpetas app/ que usarás el resto de la guía. Al terminar, tu proyecto está listo para escribir código.

Cápsula 03 — Primer endpoint y uvicorn: Escribirás tu primer endpoint GET, entenderás qué es una "path operation function" (la unidad básica de FastAPI), experimentarás con hot reload, y crearás endpoints con path parameters dinámicos. Es donde FastAPI empieza a sentirse real.

Cápsula 04 — Documentación automática: Descubrirás /docs (Swagger UI) y /redoc (ReDoc), las dos interfaces que FastAPI genera automáticamente. Aprenderás a personalizar la documentación con títulos, descripciones, tags y docstrings. Probarás endpoints directamente desde el navegador.

Cápsula 05 — Proyecto Hello World API: Integrarás todo en un mini-proyecto con 6+ endpoints, documentación personalizada, path parameters con validación de tipos, y estructura profesional. Es el entregable del módulo y la base del proyecto evolutivo.

¿Qué construirás?

Proyecto del módulo: Hello World API

Un API con múltiples endpoints GET que:

  • Responde en la ruta raíz (/) con información del servicio
  • Tiene un endpoint de health check (/health)
  • Saluda por nombre (/greet/{name})
  • Retorna JSON estructurado en todas las respuestas
  • Tiene documentación automática navegable

Este proyecto es el esqueleto. Los módulos 2-5 le agregarán CRUD completo, validación con Pydantic, error handling profesional y CORS. El Módulo 6 lo integrará todo en una To-Do List API completa.

Conexión con el proyecto final de la guía

Todo lo que configures aquí — el virtual environment, la estructura de carpetas, uvicorn — lo usarás en los 5 módulos restantes. No es setup descartable: es la base real de tu proyecto evolutivo.

Módulo 1: Hello World API (esqueleto)
    ↓
Módulo 2: + CRUD endpoints (GET, POST, PUT, DELETE)
    ↓
Módulo 3: + Path params, query params, request body
    ↓
Módulo 4: + Validación con Pydantic
    ↓
Módulo 5: + Error handling + CORS
    ↓
Módulo 6: To-Do List API completa (integración)

¿Qué NO se cubre en este módulo?

Es importante saber los límites para que no te frustres buscando algo que viene después:

  • ❌ POST, PUT, DELETE — Se cubren en Módulo 2 (Path Operations)
  • ❌ Path parameters y query parameters avanzados — Se cubren en Módulo 3 (Request y Response)
  • ❌ Pydantic models y validación — Se cubren en Módulo 4
  • ❌ Error handling y HTTPException — Se cubren en Módulo 5
  • ❌ Bases de datos — Esta guía usa datos en memoria. Las bases de datos van en guías posteriores del path
  • ❌ Deployment — Solo desarrollo local con uvicorn. Deploy va en la guía de Deployment (#13)
  • ❌ Testing — Se cubre en la guía de Testing (#11)

Este módulo es sobre setup + GET + documentación automática. Nada más, nada menos.

¿Por qué estos límites?

Cada tema omitido tiene una razón pedagógica:

  • POST/PUT/DELETE requieren entender request body — que se cubre en Módulo 3 después de que domines parámetros
  • Pydantic necesita múltiples endpoints funcionando — primero construyes endpoints, luego les agregas validación
  • Error handling asume que ya escribes endpoints — primero lo que funciona, luego lo que puede fallar
  • Bases de datos son scope de otra guía — esta guía demuestra que puedes construir APIs funcionales con datos en memoria. La persistencia viene después

¿Por qué FastAPI?

Antes de arrancar, contexto rápido de por qué esta guía usa FastAPI y no Flask, Django u otro framework.

Historia breve

FastAPI fue creado por Sebastián Ramírez en 2018. Nació de la frustración con los frameworks existentes: Flask no tenía validación automática ni documentación integrada, Django era demasiado opinado para APIs puras, y los frameworks async de la época eran inmaduros. Ramírez construyó FastAPI sobre dos pilares sólidos: Starlette (framework ASGI de alto rendimiento) y Pydantic (validación de datos con type hints).

En pocos años se convirtió en uno de los frameworks Python más populares del mundo, usado por Netflix, Uber, Microsoft y miles de startups.

Comparación con otros frameworks

CriterioFastAPIFlaskDjango
PerformanceAlta (async nativo)MediaMedia
Docs automáticasSí (Swagger + ReDoc)No (necesita extensión)No (necesita extensión)
ValidaciónAutomática (Pydantic)ManualParcial (forms)
Type hintsCore del frameworkOpcionalOpcional
Curva de aprendizajeModeradaBajaAlta
Ideal para APIsSí (diseñado para eso)Sí (pero genérico)No (más para web apps)

¿Cuándo usar cada uno?

  • FastAPI: APIs REST, microservicios, backends para frontends modernos. Es la mejor opción cuando tu proyecto es una API pura.
  • Flask: Proyectos pequeños, prototipos rápidos, o cuando necesitas máxima flexibilidad sin opiniones del framework.
  • Django: Aplicaciones web completas con admin panel, autenticación integrada, ORM propio. Mejor para proyectos full-stack con templates HTML.

FastAPI fue diseñado específicamente para construir APIs modernas. Para el path Backend Python Developer, es la elección correcta.

Las 3 features killer de FastAPI

  1. Documentación automática: Con solo escribir tus endpoints, FastAPI genera interfaces interactivas donde puedes probar tu API desde el navegador. No escribes documentación por separado — está siempre sincronizada con tu código.

  2. Validación automática con type hints: Defines item_id: int en tu función y FastAPI valida que el parámetro sea un entero. Si alguien envía "abc", retorna un error 422 descriptivo. Sin que escribas una sola línea de validación.

  3. Performance comparable a Node.js y Go: Gracias a Starlette y async nativo, FastAPI es uno de los frameworks Python más rápidos. En benchmarks, compete con frameworks de lenguajes compilados.

FastAPI en números

  • 80,000+ estrellas en GitHub (uno de los repos Python más populares)
  • Top 3 framework web en Python por adopción
  • Usado por: Netflix, Uber, Microsoft, Explosion AI (creadores de spaCy)
  • Creado en 2018 — relativamente joven pero con adopción masiva
  • Basado en estándares: OpenAPI, JSON Schema, OAuth2

Cómo seguir esta guía

Enfoque práctico

Cada cápsula incluye código que debes escribir y ejecutar. No solo leas — escribe el código tú mismo. La diferencia entre leer un ejemplo y escribirlo es la diferencia entre entender y dominar.

Flujo recomendado por cápsula

  1. Lee la descripción — Entiende qué vas a aprender y por qué importa
  2. Escribe el código — No copies y pegues. Escríbelo. Los errores de tipeo te enseñan
  3. Ejecuta y experimenta — Modifica los ejemplos. ¿Qué pasa si cambias un valor? ¿Un tipo?
  4. Haz los ejercicios — Intenta resolver sin ver la solución primero
  5. Revisa la solución — Compara tu enfoque con la solución propuesta

Tiempo estimado

  • Cápsula de introducción (esta): 15-20 minutos
  • Cápsulas técnicas (02-04): 25-40 minutos cada una
  • Proyecto (05): 30-45 minutos
  • Total Módulo 1: 1.5-2 horas

No apures. Si un concepto no queda claro, relee antes de avanzar. Cada módulo construye sobre el anterior — los vacíos se acumulan.

Conceptos clave que aprenderás

Antes de entrar al código, estos son los conceptos centrales del módulo:

Virtual Environment

Un espacio aislado donde instalas las dependencias de tu proyecto sin afectar otros proyectos Python en tu máquina. Cada proyecto tiene su propio "departamento" de librerías.

uvicorn

El servidor que ejecuta tu aplicación FastAPI. FastAPI por sí solo no puede recibir conexiones HTTP — uvicorn escucha en un puerto, recibe requests, y los pasa a FastAPI para procesarlos.

Path Operation

La unidad básica de FastAPI: una combinación de ruta HTTP (/health), verbo HTTP (GET), y función Python (def health_check()). Es como un switch: "si llega un GET a /health, ejecuta esta función."

Hot Reload

La capacidad de uvicorn de reiniciar automáticamente cuando cambias código. Guardas un archivo y el servidor se actualiza sin que hagas nada. Acelera dramáticamente el ciclo de desarrollo.

OpenAPI / Swagger

El estándar que FastAPI usa para generar documentación automática. Tu código Python se convierte en un schema JSON que las interfaces /docs y /redoc renderizan como documentación interactiva.

Setup técnico previo

Antes de la siguiente cápsula, verifica que tienes todo listo:

1. Python 3.9+

python --version
# Debe mostrar: Python 3.9.x o superior

# En algunos sistemas:
python3 --version

Si tienes una versión inferior, actualiza Python antes de continuar. FastAPI requiere 3.9+ por las features de type hints que usa internamente.

2. pip actualizado

pip --version
# Debe mostrar versión de pip y ubicación

# Actualizar pip:
pip install --upgrade pip

3. Editor de código

VS Code es el recomendado. Si lo usas, instala estas extensiones:

  • Python (Microsoft) — IntelliSense, debugging, linting
  • Pylance (Microsoft) — Type checking avanzado, autocompletado de FastAPI

Otros editores como PyCharm, Sublime Text o Vim funcionan igual — lo importante es que tengas syntax highlighting para Python y una terminal integrada.

4. Terminal

Necesitas una terminal donde puedas ejecutar comandos. En VS Code puedes usar la terminal integrada (Ctrl+ñ o Cmd+ñ). En Mac, la app Terminal. En Windows, PowerShell o Windows Terminal.

Tendrás dos terminales abiertas frecuentemente:

  • Una para uvicorn (servidor corriendo)
  • Otra para curl o comandos (probar endpoints)

5. Navegador web

Necesitas un navegador moderno (Chrome, Firefox, Edge) para acceder a la documentación automática en /docs. Las dev tools del navegador (F12) también son útiles para inspeccionar requests HTTP.

Si alguno de estos pasos falla, resuélvelo antes de continuar. La Cápsula 02 asume que Python, pip y tu editor están funcionando.

El stack que vas a usar

Para que tengas claro qué tecnologías intervienen en este módulo y su función:

Tu código Python (app/main.py)
    ↓ define endpoints con decoradores
FastAPI (framework)
    ↓ parsea requests, valida datos, serializa responses
Starlette (framework ASGI subyacente)
    ↓ maneja routing, middleware, sesiones HTTP
uvicorn (servidor ASGI)
    ↓ escucha en puerto 8000, recibe/envía HTTP
Cliente (navegador, curl, /docs)
    ↓ envía requests, recibe responses

Tú solo escribes la capa superior (tu código Python). FastAPI, Starlette y uvicorn se encargan del resto. Esta es la magia del framework: abstraer la complejidad de HTTP, concurrencia y serialización para que te enfoques en la lógica de tu API.

En este módulo no necesitas entender los detalles de cada capa. Solo saber que existen y que trabajan en equipo.

Evidencia de éxito

Al terminar este módulo (las 5 cápsulas), sabrás que tuviste éxito si:

  • ✅ Tienes un virtual environment creado y activado con FastAPI instalado
  • ✅ Tu proyecto tiene estructura de carpetas profesional (no todo en un archivo)
  • ✅ Un servidor uvicorn corre con hot reload y responde en http://localhost:8000
  • ✅ Puedes navegar a http://localhost:8000/docs y ver la documentación interactiva
  • ✅ Puedes crear un endpoint GET, guardar el archivo, y ver el cambio reflejado sin reiniciar
  • ✅ Tu Hello World API tiene al menos 6 endpoints funcionando con respuestas JSON
  • ✅ La documentación muestra endpoints organizados por tags

Resumen

  • Este es el Módulo 1 de la guía FastAPI Fundamentals, la primera guía del nivel intermedio del path Backend Python Developer
  • Cubre instalación, setup, primer endpoint, uvicorn con hot reload, y documentación automática
  • El proyecto del módulo es un Hello World API que servirá de esqueleto para toda la guía
  • Requiere Python 3.9+, pip, un editor de código y conocimiento previo de HTTP y Python básico
  • No cubre POST/PUT/DELETE, validación, error handling ni bases de datos — eso viene en módulos siguientes
  • FastAPI fue elegido por su rendimiento, documentación automática y validación integrada con type hints
  • Los conceptos clave del módulo son: virtual environment, uvicorn, path operations, hot reload y OpenAPI
  • El enfoque es práctico — escribe código, ejecútalo, modifícalo y haz los ejercicios

Recursos adicionales

  1. FastAPI - Documentación oficial - El recurso principal. Tutorial excelente y referencia completa
  2. FastAPI en GitHub - Código fuente, issues, y ejemplos de la comunidad
  3. Uvicorn - Documentación oficial - El servidor ASGI que usarás para correr FastAPI
  4. Python venv - Docs oficiales - Referencia de virtual environments
  5. OpenAPI Specification - El estándar que FastAPI usa para generar documentación
  6. Sebastián Ramírez - Creador de FastAPI (Talk) - Charla del creador explicando las decisiones de diseño

Siguiente cápsula: Instalación y setup — Crearás tu virtual environment, instalarás FastAPI y configurarás la estructura de proyecto que usarás en toda la guía.

Next →¿Qué es FastAPI?