Skip to content

marr-cloud/bread-api

BranchesTags

Repository files navigation

🍞 Bread API

API REST que sirve información sobre diferentes tipos de pan del mundo. Construida con Cloudflare Workers, HonoJS, D1, Prisma y Zod.

URL de Producción: https://bread-api.infraforge.cc

🔧 Stack Tecnológico

  • Runtime: Cloudflare Workers
  • Framework: HonoJS
  • Base de datos: Cloudflare D1 (SQLite)
  • ORM: Prisma con adaptador D1
  • Validación: Zod
  • Lenguaje: TypeScript
  • Package Manager: pnpm

📋 Estructura de Datos

Cada pan contiene la siguiente información:

{
  id: number;
  name: string;
  country: string;
  year_created: number | null;
  description: string;
  characteristics: string[];
  ingredients: string[];
  image_url: string;
  created_at: Date;
  updated_at: Date;
}

🚀 Endpoints

GET /

Información general de la API.

Respuesta:

{
  "name": "Bread API",
  "version": "1.0.0",
  "description": "API serving information about world-famous breads",
  "endpoints": {
    "breads": "/breads",
    "breadById": "/breads/:id"
  }
}

GET /breads

Lista todos los panes con soporte para filtros y paginación.

Query Parameters:

  • country (opcional): Filtrar por país (case-insensitive). Ejemplo: ?country=France
  • search (opcional): Buscar en nombre y descripción. Ejemplo: ?search=sour
  • limit (opcional): Número de resultados (default: 20, max: 100). Ejemplo: ?limit=10
  • offset (opcional): Offset para paginación (default: 0). Ejemplo: ?offset=10

Ejemplo de Petición:

curl "https://bread-api.infraforge.cc/breads?country=France&limit=5"

Respuesta:

{
  "data": [
    {
      "id": 1,
      "name": "Baguette",
      "country": "France",
      "year_created": 1920,
      "description": "A long, thin loaf of French bread...",
      "characteristics": [
        "Crispy golden crust",
        "Soft, airy interior with large holes"
      ],
      "ingredients": ["Wheat flour", "Water", "Salt", "Yeast"],
      "image_url": "https://images.unsplash.com/...",
      "created_at": "2025-12-19T20:00:00.000Z",
      "updated_at": "2025-12-19T20:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 5,
  "offset": 0
}

GET /breads/:id

Obtiene los detalles completos de un pan específico.

Path Parameters:

  • id: ID numérico del pan

Ejemplo de Petición:

curl "https://bread-api.infraforge.cc/breads/1"

Respuesta:

{
  "id": 1,
  "name": "Baguette",
  "country": "France",
  "year_created": 1920,
  "description": "A long, thin loaf of French bread...",
  "characteristics": [
    "Crispy golden crust",
    "Soft, airy interior with large holes",
    "Long and thin shape (60-70cm)",
    "Light and slightly chewy texture"
  ],
  "ingredients": ["Wheat flour", "Water", "Salt", "Yeast"],
  "image_url": "https://images.unsplash.com/...",
  "created_at": "2025-12-19T20:00:00.000Z",
  "updated_at": "2025-12-19T20:00:00.000Z"
}

Errores:

  • 404: Pan no encontrado
  • 400: ID inválido

🛠️ Desarrollo Local

Prerrequisitos

  • Node.js 18+
  • pnpm (o npm/yarn)
  • Cuenta de Cloudflare con D1

1. Instalación

# Clonar el repositorio
git clone <repo-url>
cd bread-api

# Instalar dependencias
pnpm install

2. Configuración

Las credenciales de Cloudflare D1 ya están configuradas en wrangler.jsonc:

  • Account ID: a27eeb35a8bef00d5bff5170a654c417
  • Database ID: 77ed88f9-a1b4-4927-aa2c-7f61c88fb45c
  • Database Name: bread-db

3. Generar el Cliente de Prisma

pnpm prisma:generate

Este comando genera el cliente de Prisma basado en el esquema definido en prisma/schema.prisma.

4. Crear y Ejecutar Migraciones

# Crear una nueva migración
pnpm prisma:migrate

# Ejecutar la migración en D1 remoto
pnpm wrangler d1 execute bread-db --remote --file=./prisma/migrations/<nombre_migracion>/migration.sql

Nota: Como D1 es una base de datos remota, las migraciones deben ejecutarse usando el CLI de Wrangler.

5. Poblar la Base de Datos (Seed)

El seed script contiene 20 panes famosos del mundo con datos reales e históricos.

# Para desarrollo local (requiere configuración adicional)
# Este comando usa una base de datos SQLite local
pnpm seed

# Para ejecutar seed en D1 remoto, necesitas adaptar el script o insertar datos manualmente

Nota: El script de seed está configurado para SQLite local. Para D1, considera ejecutar el seed localmente primero y luego migrar o adaptar el script para usar D1.

6. Ejecutar en Desarrollo

pnpm dev

La API estará disponible en http://localhost:8787

7. Probar los Endpoints

# Listar todos los panes
curl http://localhost:8787/breads

# Filtrar por país
curl "http://localhost:8787/breads?country=France"

# Buscar
curl "http://localhost:8787/breads?search=sour"

# Obtener un pan específico
curl http://localhost:8787/breads/1

# Paginación
curl "http://localhost:8787/breads?limit=5&offset=5"

🚢 Despliegue a Producción

1. Configurar Wrangler

Asegúrate de estar autenticado con Cloudflare:

pnpm wrangler login

2. Verificar Configuración

El archivo wrangler.jsonc ya está configurado con:

  • Nombre del worker: bread-api
  • Binding de D1: DB
  • Compatibilidad con Node.js para Prisma

3. Ejecutar Migraciones en Producción

# Ejecutar la migración en la base de datos D1 remota
pnpm wrangler d1 execute bread-db --remote --file=./prisma/migrations/<nombre_migracion>/migration.sql

4. Desplegar

pnpm deploy

Este comando:

  • Empaqueta tu aplicación
  • Minifica el código
  • Despliega a Cloudflare Workers
  • Configura automáticamente el binding con D1

5. Verificar Despliegue

Después del despliegue, tu API estará disponible en:

  • https://bread-api.<tu-subdomain>.workers.dev
  • O en tu dominio personalizado configurado en Cloudflare

📊 Base de Datos

Dataset Incluido (20 Panes)

  1. Baguette (Francia, 1920)
  2. Ciabatta (Italia, 1982)
  3. Croissant (Francia, 1683)
  4. Sourdough (Egipto, ~3700 AC)
  5. Naan (India, 1300)
  6. Pita (Medio Oriente, ~2500 AC)
  7. Focaccia (Italia, ~500 AC)
  8. Challah (Israel, 1400)
  9. Brioche (Francia, 1404)
  10. Pretzel (Alemania, 610)
  11. Pan de Bono (Colombia, 1850)
  12. Tortilla (México, ~500 AC)
  13. Pumpernickel (Alemania, 1450)
  14. Bagel (Polonia, 1610)
  15. Injera (Etiopía, ~100 AC)
  16. Roti (India, ~2500 AC)
  17. Cornbread (Estados Unidos, 1700)
  18. Pan de Muerto (México, 1500)
  19. Damper (Australia, 1800)
  20. Arepa (Venezuela, ~3000 AC)

Estructura de la Tabla

CREATE TABLE Bread (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    country TEXT NOT NULL,
    year_created INTEGER,
    description TEXT NOT NULL,
    characteristics TEXT NOT NULL,  -- JSON array
    ingredients TEXT NOT NULL,      -- JSON array
    image_url TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_bread_country ON Bread(country);
CREATE INDEX idx_bread_name ON Bread(name);

🧪 Comandos Útiles

# Desarrollo
pnpm dev                    # Ejecutar en modo desarrollo
pnpm deploy                 # Desplegar a producción

# Prisma
pnpm prisma:generate        # Generar cliente de Prisma
pnpm prisma:migrate         # Crear nueva migración

# Base de datos
pnpm wrangler d1 execute bread-db --remote --command="SELECT * FROM Bread LIMIT 5"
pnpm wrangler d1 execute bread-db --local --command="SELECT * FROM Bread"

# Seed
pnpm seed                   # Poblar base de datos local

📁 Estructura del Proyecto

bread-api/
├── prisma/
│   ├── schema.prisma       # Esquema de Prisma
│   ├── seed.ts            # Script de seed con 20 panes
│   └── migrations/        # Migraciones SQL
├── src/
│   ├── index.ts           # Entrada principal de la app
│   ├── types.ts           # Definiciones de tipos
│   ├── validators.ts      # Validadores Zod
│   └── routes/
│       └── breads.ts      # Rutas de panes
├── wrangler.jsonc         # Configuración de Cloudflare Workers
├── tsconfig.json          # Configuración de TypeScript
├── package.json           # Dependencias y scripts
└── README.md             # Este archivo

🔒 Seguridad y Limitaciones

  • Solo lectura: La API solo expone endpoints GET. La administración de datos se hace manualmente en D1.
  • CORS: Habilitado para todas las rutas.
  • Rate Limiting: Usa los límites por defecto de Cloudflare Workers (100k requests/día en plan gratuito).
  • Validación: Todos los parámetros de entrada son validados con Zod.

🐛 Troubleshooting

Error: "Cannot find module '@prisma/client'"

pnpm prisma:generate

Error al migrar D1

Asegúrate de usar el flag --remote para la base de datos en la nube:

pnpm wrangler d1 execute bread-db --remote --file=./prisma/migrations/xxx/migration.sql

Problemas con el seed

El seed script usa SQLite local. Para D1, considera:

  1. Ejecutar el seed localmente primero
  2. Exportar los datos
  3. Importarlos a D1 usando wrangler

📝 Licencia

MIT

👨‍💻 Autor

Desarrollado para demostrar el uso de Cloudflare Workers, D1, y tecnologías modernas de TypeScript.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages