Skip to main content
Get your first API call working in minutes. This guide will walk you through starting the server and making your first request to check classroom availability.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.8 or higher installed
  • pip package manager
  • Basic understanding of REST APIs

​
Start the Server

1

Install Dependencies

Install all required packages from the requirements.txt file:
pip install -r requirements.txt
Key dependencies include:
  • FastAPI: Modern, fast web framework for building APIs
  • Uvicorn: ASGI server for running FastAPI applications
  • Pydantic: Data validation using Python type annotations
  • OR-Tools: Google’s optimization tools for scheduling
2

Run the Development Server

Start the FastAPI server using Uvicorn:
uvicorn src.main:app --reload
The server will start on http://localhost:8000 with auto-reload enabled for development.
The --reload flag enables hot-reloading, automatically restarting the server when code changes are detected.
3

Verify the Server

Check that the API is running by visiting the health endpoint:
curl http://localhost:8000/api/v1/health
Expected response:
{
  "status": "healthy",
  "service": "Gestión de Horarios",
  "version": "1.0.0"
}

​
Make Your First API Call

Let’s find available classrooms for a specific course and time slot.

​
Check Available Classrooms

The most common operation is checking which classrooms are available for a course at a specific time. This endpoint applies all restrictions: capacity, compatibility, and availability. 
curl -X POST http://localhost:8000/api/v1/aulas-disponibles \
  -H "Content-Type: application/json" \
  -d '{
    "asignatura_id": "A001",
    "hora_inicio": "08:00",
    "hora_fin": "10:00",
    "dia": "Lunes",
    "cantidad_estudiantes": 30,
    "semestre": 1
  }'

​
Understanding the Response

The API returns comprehensive information about available and unavailable classrooms: 
{
  "asignatura": {
    "id": "A001",
    "nombre": "Álgebra Lineal",
    "tipo": "teorica"
  },
  "horario_solicitado": {
    "dia": "Lunes",
    "hora_inicio": "08:00",
    "hora_fin": "10:00",
    "cantidad_estudiantes": 30,
    "semestre": 1
  },
  "aulas_disponibles": [
    {
      "id": "AU001",
      "nombre": "Aula 101",
      "tipo": "teorica",
      "capacidad": 40,
      "sede": {
        "id": "S001",
        "nombre": "Sede Principal"
      },
      "recursos": [
        {
          "id": "R001",
          "nombre": "Proyector"
        },
        {
          "id": "R002",
          "nombre": "Pizarra Digital"
        }
      ]
    }
  ],
  "aulas_no_disponibles": [
    {
      "id": "AU002",
      "nombre": "Lab Computo 1",
      "razon": "Tipo incompatible: laboratorio no es compatible con asignatura teorica"
    }
  ],
  "total_disponibles": 1,
  "total_no_disponibles": 1,
  "error": null
}
Key Response Fields:
  • aulas_disponibles: Classrooms that meet all requirements (capacity, type compatibility, time availability)
  • aulas_no_disponibles: Classrooms that don’t meet requirements, with reasons why
  • total_disponibles: Count of available classrooms

​
Reserve a Classroom

Once you’ve found an available classroom, reserve it for your course: 
curl -X POST http://localhost:8000/api/v1/reservar-aula \
  -H "Content-Type: application/json" \
  -d '{
    "asignatura_id": "A001",
    "aula_id": "AU001",
    "fecha": "2024-03-15",
    "dia": "Lunes",
    "hora_inicio": "08:00",
    "hora_fin": "10:00",
    "cantidad_estudiantes": 30,
    "semestre": 1,
    "docente_id": "D001",
    "id_usuario": "user123"
  }'
Expected response: 
{
  "success": true,
  "message": "Aula reservada exitosamente",
  "programacion_id": "PROG-2024-001",
  "estado": "reservado"
}
The API validates that the classroom is actually available before confirming the reservation. If the classroom becomes unavailable between checking and reserving, the request will fail with a 400 error.

​
Explore the API

Now that you have the basics working, explore more endpoints:

Get Catalog Data

Retrieve all classrooms, courses, teachers, and resources

Manage Schedules

Create and manage complete semester schedules

View Reservations

List all classroom reservations and their status

API Documentation

Interactive API documentation (Swagger UI)

​
Interactive API Documentation

FastAPI automatically generates interactive API documentation. With your server running, visit: These interfaces allow you to test all endpoints directly from your browser.

​
Next Steps

Installation Guide

Detailed setup instructions and configuration options

API Reference

Complete API endpoint documentation

Architecture

Learn about the system’s design patterns

Constraint Validation

Learn about the validation system

​
Common Issues

If port 8000 is already in use, specify a different port:
uvicorn src.main:app --reload --port 8001
Ensure you’re running the command from the project root directory and all dependencies are installed:
pip install -r requirements.txt
Time must be in HH:MM format (24-hour). Valid examples: “08:00”, “14:30”, “23:59”
Day must be one of: Lunes, Martes, Miércoles, Jueves, Viernes, Sábado, Domingo

Build docs developers (and LLMs) love

Get started for freeTalk to us