API Layer

Implementation Status: The API controllers are currently stub files and not yet implemented. This documentation describes the planned architecture and patterns that will be used when the controllers are built.

The API layer (SGRH.Api) will provide the HTTP interface to the application, exposing REST endpoints that invoke application use cases. Controllers will be thin orchestrators that handle HTTP concerns while delegating business logic to the Application layer.

Current Implementation

Currently, only one controller is implemented:

TestDbController (/api/test-db/ping) - Database connectivity testing

The other controller files exist as empty stubs:

ClientesController.cs
ReservasController.cs
HabitacionesController.cs
ServiciosAdicionalesController.cs
TarifasTemporadasController.cs
ReportesController.cs
AuditoriaController.cs

Project Structure

SGRH.Api/
├── Controllers/
│   ├── ReservasController.cs
│   ├── HabitacionesController.cs
│   ├── ClientesController.cs
│   ├── ServiciosAdicionalesController.cs
│   ├── TarifasTemporadasController.cs
│   ├── ReportesController.cs
│   ├── AuditoriaController.cs
│   └── TestDbController.cs
├── Program.cs                     # Application entry point
├── appsettings.json              # Configuration
└── appsettings.Development.json

Program.cs Configuration

The application bootstraps services and middleware in Program.cs:

using Microsoft.EntityFrameworkCore;
using SGRH.Persistence.Context;

namespace SGRH.Api
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            // Add services to the container
            builder.Services.AddControllers();
            builder.Services.AddEndpointsApiExplorer();
            builder.Services.AddSwaggerGen();

            // Database configuration
            builder.Services.AddDbContext<SGRHDbContext>(options =>
                options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

            var app = builder.Build();

            // HTTPS redirection (production only)
            if (!app.Environment.IsDevelopment())
            {
                app.UseHttpsRedirection();
            }

            // Swagger (development only)
            if (app.Environment.IsDevelopment())
            {
                app.UseSwagger();
                app.UseSwaggerUI();
            }

            app.UseAuthorization();
            app.MapControllers();

            app.Run();
        }
    }
}

The current Program.cs shows basic setup. In a complete implementation, this would also call AddInfrastructure() and AddApplication() extension methods.

Controller Pattern

Base Controller Structure

Controllers follow ASP.NET Core conventions with attribute routing:

[ApiController]
[Route("api/[controller]")]
public class ReservasController : ControllerBase
{
    private readonly IMediator _mediator; // or direct service injection
    private readonly ILogger<ReservasController> _logger;

    public ReservasController(IMediator mediator, ILogger<ReservasController> logger)
    {
        _mediator = mediator;
        _logger = logger;
    }

    // Endpoints...
}

HTTP Method Mapping

GET - Queries
POST - Create
PUT - Update
DELETE - Remove

/// <summary>
/// Get all reservations with optional filters
/// </summary>
[HttpGet]
[ProducesResponseType(typeof(PagedResult<ReservaListDto>), StatusCodes.Status200OK)]
public async Task<ActionResult<PagedResult<ReservaListDto>>> GetReservas(
    [FromQuery] ListarReservasQuery query,
    CancellationToken ct)
{
    var result = await _mediator.Send(query, ct);
    return Ok(result);
}

/// <summary>
/// Get reservation by ID with full details
/// </summary>
[HttpGet("{id}")]
[ProducesResponseType(typeof(ReservaDto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<ReservaDto>> GetReservaById(int id, CancellationToken ct)
{
    var query = new ObtenerReservaPorIdQuery { ReservaId = id };
    var result = await _mediator.Send(query, ct);
    
    if (result == null)
        return NotFound(new { message = $"Reserva {id} no encontrada" });
    
    return Ok(result);
}

/// <summary>
/// Create a new reservation
/// </summary>
[HttpPost]
[ProducesResponseType(typeof(ReservaDto), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<ActionResult<ReservaDto>> CrearReserva(
    [FromBody] CrearReservaCommand command,
    CancellationToken ct)
{
    var result = await _mediator.Send(command, ct);
    
    return CreatedAtAction(
        nameof(GetReservaById),
        new { id = result.ReservaId },
        result);
}

/// <summary>
/// Update an existing reservation
/// </summary>
[HttpPut("{id}")]
[ProducesResponseType(typeof(ReservaDto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<ReservaDto>> ActualizarReserva(
    int id,
    [FromBody] ActualizarReservaCommand command,
    CancellationToken ct)
{
    if (id != command.ReservaId)
        return BadRequest(new { message = "ID mismatch" });
    
    var result = await _mediator.Send(command, ct);
    return Ok(result);
}

/// <summary>
/// Cancel a reservation
/// </summary>
[HttpDelete("{id}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> CancelarReserva(int id, CancellationToken ct)
{
    var command = new CancelarReservaCommand { ReservaId = id };
    await _mediator.Send(command, ct);
    
    return NoContent();
}

Controller Endpoints by Feature

ReservasController

GET /api/reservas

List reservations with filtersQuery Parameters:

fechaDesde (DateTime?): Filter by start date
fechaHasta (DateTime?): Filter by end date
estado (EstadoReserva?): Filter by status
clienteId (int?): Filter by client
pageNumber (int): Page number (default: 1)
pageSize (int): Items per page (default: 20)

Response: PagedResult<ReservaListDto>

GET /api/reservas/{id}

Get reservation detailsIncludes full details: rooms, services, pricingResponse: ReservaDto

POST /api/reservas

Create new reservationRequest Body:

{
  "clienteId": 1,
  "fechaEntrada": "2024-12-20",
  "fechaSalida": "2024-12-25",
  "habitacionIds": [101, 102]
}

Response: 201 Created with ReservaDto

PUT /api/reservas/{id}

Update reservationCan modify dates, add/remove rooms and services (only if Pendiente)

POST /api/reservas/{id}/confirmar

Confirm reservationTransitions state: Pendiente → Confirmada

POST /api/reservas/{id}/checkin

Check-in guestValidates current date matches entry date, changes room states

POST /api/reservas/{id}/checkout

Check-out guestFinalizes reservation, frees rooms

DELETE /api/reservas/{id}

Cancel reservationTransitions to Cancelada state

HabitacionesController

GET /api/habitaciones

List rooms with availabilityQuery Parameters:

categoriaId (int?): Filter by category
estado (EstadoHabitacion?): Filter by status
fechaDesde (DateTime?): Check availability from
fechaHasta (DateTime?): Check availability to

Response: List<HabitacionDto>

GET /api/habitaciones/{id}

Get room detailsIncludes current status and history

POST /api/habitaciones

Create new roomRequest Body:

{
  "categoriaHabitacionId": 1,
  "numeroHabitacion": 101,
  "piso": 1
}

PUT /api/habitaciones/{id}

Update room informationCan change category, floor, etc.

PUT /api/habitaciones/{id}/estado

Change room statusRequest Body:

{
  "nuevoEstado": "Mantenimiento",
  "motivo": "Reparación de aire acondicionado"
}

ClientesController

GET /api/clientes

List all clientsSupports pagination and search

GET /api/clientes/{id}

Get client detailsIncludes contact information and reservation history

POST /api/clientes

Register new clientRequest Body:

{
  "nationalId": "12345678",
  "nombreCliente": "Juan",
  "apellidoCliente": "Pérez",
  "email": "[email protected]",
  "telefono": "+1234567890"
}

PUT /api/clientes/{id}

Update client informationCannot change NationalId (immutable)

DELETE /api/clientes/{id}

Delete clientOnly if no active reservations

ServiciosAdicionalesController

GET /api/servicios

List available servicesCan filter by season availability

POST /api/servicios

Create new serviceRequest Body:

{
  "nombreServicio": "Spa",
  "tipoServicio": "Wellness"
}

PUT /api/servicios/{id}

Update service

DELETE /api/servicios/{id}

Delete service

TarifasTemporadasController

GET /api/tarifas

List rates by season and category

POST /api/tarifas

Create new rateRequest Body:

{
  "categoriaHabitacionId": 1,
  "temporadaId": 2,
  "precio": 150.00
}

GET /api/temporadas

List seasons

POST /api/temporadas

Create new seasonRequest Body:

{
  "nombreTemporada": "Verano 2024",
  "fechaInicio": "2024-06-01",
  "fechaFin": "2024-08-31"
}

ReportesController

GET /api/reportes/ocupacion

Occupancy reportQuery Parameters:

fechaInicio (DateTime)
fechaFin (DateTime)

Returns occupancy rates by room and period

GET /api/reportes/ingresos

Revenue reportBreakdown by rooms and services

GET /api/reportes/reservas

Reservation analyticsStatistics and trends

AuditoriaController

GET /api/auditoria

Query audit logsQuery Parameters:

entidad (string): Entity type
accion (string): Action performed
usuarioId (int?): User filter
fechaDesde (DateTime?)
fechaHasta (DateTime?)

Error Handling

Global Exception Handler

public class ExceptionHandlerMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        try
        {
            await next(context);
        }
        catch (NotFoundException ex)
        {
            context.Response.StatusCode = StatusCodes.Status404NotFound;
            await context.Response.WriteAsJsonAsync(new { error = ex.Message });
        }
        catch (ValidationException ex)
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            await context.Response.WriteAsJsonAsync(new { error = ex.Message });
        }
        catch (BusinessRuleViolationException ex)
        {
            context.Response.StatusCode = StatusCodes.Status422UnprocessableEntity;
            await context.Response.WriteAsJsonAsync(new { error = ex.Message });
        }
        catch (ConflictException ex)
        {
            context.Response.StatusCode = StatusCodes.Status409Conflict;
            await context.Response.WriteAsJsonAsync(new { error = ex.Message });
        }
        catch (Exception ex)
        {
            context.Response.StatusCode = StatusCodes.Status500InternalServerError;
            await context.Response.WriteAsJsonAsync(new { error = "Internal server error" });
        }
    }
}

HTTP Status Code Mapping

Domain Exception	HTTP Status	Usage
`NotFoundException`	404 Not Found	Entity doesn’t exist
`ValidationException`	400 Bad Request	Invalid input data
`BusinessRuleViolationException`	422 Unprocessable Entity	Business rule violation
`ConflictException`	409 Conflict	Duplicate or conflicting state
Generic Exception	500 Internal Server Error	Unexpected errors

Swagger/OpenAPI Configuration

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "SGRH API",
        Version = "v1",
        Description = "Sistema de Gestión de Reservas Hoteleras",
        Contact = new OpenApiContact
        {
            Name = "SGRH Team",
            Email = "[email protected]"
        }
    });

    // Include XML comments
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);

    // Add JWT authentication
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT"
    });
});

CORS Configuration

builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowFrontend", builder =>
    {
        builder.WithOrigins("http://localhost:3000", "https://sgrh.com")
               .AllowAnyMethod()
               .AllowAnyHeader()
               .AllowCredentials();
    });
});

// In middleware pipeline
app.UseCors("AllowFrontend");

Authentication & Authorization

[Authorize(Roles = "Admin")]
[HttpPost]
public async Task<IActionResult> CrearHabitacion([FromBody] CrearHabitacionCommand cmd)
{
    // Only admins can create rooms
}

[Authorize]
[HttpGet("mis-reservas")]
public async Task<IActionResult> GetMisReservas()
{
    var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
    // Return reservations for current user
}

Key Design Decisions

Thin Controllers

Controllers only handle HTTP concerns, delegate to Application layer

RESTful Conventions

Standard HTTP verbs and status codes for predictable API

Centralized Error Handling

Middleware translates domain exceptions to HTTP responses

API Versioning Ready

Route structure supports versioning (/api/v1/…)

Application Layer

See commands and queries invoked by controllers

Domain Layer

Understand entities and exceptions

Infrastructure

Learn about DI configuration

Getting Started

Architecture

Core Concepts

Configuration

API Layer

API Layer

Current Implementation

Project Structure

Program.cs Configuration

Controller Pattern

Base Controller Structure

HTTP Method Mapping

Controller Endpoints by Feature

ReservasController

HabitacionesController

ClientesController

ServiciosAdicionalesController

TarifasTemporadasController

ReportesController

AuditoriaController

Error Handling

Global Exception Handler

HTTP Status Code Mapping

Swagger/OpenAPI Configuration

CORS Configuration

Authentication & Authorization

Key Design Decisions

Thin Controllers

RESTful Conventions

Centralized Error Handling

API Versioning Ready

Application Layer

Domain Layer

Infrastructure

Build docs developers (and LLMs) love

Getting Started

Architecture

Core Concepts

Configuration

​API Layer

​Current Implementation

​Project Structure

​Program.cs Configuration

​Controller Pattern

​Base Controller Structure

​HTTP Method Mapping

​Controller Endpoints by Feature

​ReservasController

​HabitacionesController

​ClientesController

​ServiciosAdicionalesController

​TarifasTemporadasController

​ReportesController

​AuditoriaController

​Error Handling

​Global Exception Handler

​HTTP Status Code Mapping

​Swagger/OpenAPI Configuration

​CORS Configuration

​Authentication & Authorization

​Key Design Decisions

Thin Controllers

RESTful Conventions

Centralized Error Handling

API Versioning Ready

​Related Documentation

Application Layer

Domain Layer

Infrastructure

Build docs developers (and LLMs) love

API Layer

Current Implementation

Project Structure

Program.cs Configuration

Controller Pattern

Base Controller Structure

HTTP Method Mapping

Controller Endpoints by Feature

ReservasController

HabitacionesController

ClientesController

ServiciosAdicionalesController

TarifasTemporadasController

ReportesController

AuditoriaController

Error Handling

Global Exception Handler

HTTP Status Code Mapping

Swagger/OpenAPI Configuration

CORS Configuration

Authentication & Authorization

Key Design Decisions

Related Documentation