TechsBCN.Platform.API 0.0.25

TechsBCN.Platform.API

TechsBCN.Platform.API Es la capa de presentación de Platform. Su objetivo es recibir peticiones externas, transformarlas en objetos de aplicación y delegar la lógica de negocio en la capa Application. Esta capa no contiene lógica de negocio.

Depende de TechsBCN.Platform.Application y TechsBCN.Platform.Setup.

Estructura

API/
├── Controllers/
│   └── BaseController.cs
├── Models/
│   ├── Base.cs
│   ├── BasicItem.cs
│   ├── ListRequest.cs
│   ├── ListResponse.cs
│   ├── TaskMessage.cs
│   ├── User.cs
│   └── ApiError.cs
└── Setup/
    ├── MapperProfile.cs
    ├── SwaggerSetup.cs
    ├── AuthenticationSetup.cs
    └── ErrorMiddleware.cs

Controllers (Controllers/)

BaseController

BaseController Es la clase base de todos los controllers. Su objetivo es proporcionar funcionalidad común a todos los controllers del proyecto sin tener que reimplementarla en cada uno.

Propiedades disponibles

• UserId — identificador del usuario autenticado (claim NameIdentifier).
• UserRole — rol del usuario autenticado (claim Role).
• UserName — nombre del usuario autenticado (claim Name).
• IsAuthenticated — indica si la petición está autenticada.

Métodos disponibles

• GenerateJWT(long userId, string? role = null) — genera el token JWT firmado con la configuración Auth:Jwt.
• TryGetClaimId(string claimType) — obtiene un claim y lo convierte a long.
• FindClaimValue(string claimType) — obtiene el valor de un claim como string.

Uso típico en AuthController

public class AuthController(ISecurityService SecurityService, IConfiguration Configuration)
    : BaseController(Configuration)
{
    [HttpPost]
    public ActionResult<AuthResult> Login([FromBody] AuthRequest model)
    {
        var user = SecurityService.CheckCredentials(model.Email, model.Password);
        return Ok(new AuthResult { Token = GenerateJWT(user.Id) });
    }
}

Patrón de controller

[ApiController]
[Authorize]
[Route("entities")]
[Produces("application/json")]
public class EntityController(
    IEntityService EntityService,
    IMapper Mapper
) : BaseController
{
    /// <summary>Retrieves a paginated list of entities.</summary>
    /// <param name="model">Filter and pagination criteria.</param>
    /// <response code="200">Paginated list of entities.</response>
    [HttpGet]
    [ProducesResponseType(typeof(ListResponse<Entity>), 200)]
    public ActionResult<ListResponse<Entity>> List([FromQuery] EntityListRequest model) =>
        Ok(Mapper.Map<ListResponse<Entity>>(EntityService.List(Mapper.Map<ListRequest>(model))));

    /// <summary>Retrieves an entity by identifier.</summary>
    /// <param name="id">Unique identifier of the entity.</param>
    /// <response code="200">Entity data.</response>
    /// <response code="404">Entity not found.</response>
    [HttpGet("{id:long}")]
    [ProducesResponseType(typeof(Entity), 200)]
    [ProducesResponseType(typeof(ApiError), 404, Description = "Entity not found.")]
    public ActionResult<Entity> Read(long id) =>
        Ok(Mapper.Map<Entity>(EntityService.Read(id)));
}

Models (Models/)

Entendemos por Model una clase cuyo objetivo es definir qué datos ve el cliente en cada respuesta. Los models base están disponibles para que los proyectos no los reimplementen.

Base

Model base del que extienden el resto de models de la capa API. El objetivo es que todos los models tengan un Id sin definirlo en cada uno.

public abstract class Base
{
    public long Id { get; set; }
}

BasicItem

BasicItem Es el model de elemento básico de la capa API. El objetivo es proporcionar una representación mínima de entidades que solo necesitan un Id y un Name, para aquellos proyectos que requieran mostrar listas simples o referencias a entidades sin exponer todos sus datos. Extiende Base.

public class BasicItem : Base
{
    public string? Name { get; set; }
}

ListRequest

Model que define un contrato estándar de filtrado y paginación en la capa API. El objetivo es que todos los listados reutilicen la misma estructura de entrada sin duplicarla en cada proyecto.

public class ListRequest
{
    public string? Query { get; set; }
    public int? Offset { get; set; }
    public int? Limit { get; set; }
    public string? OrderBy { get; set; }
    public bool? OrderAsc { get; set; }
}

ListResponse<T>

Model que define un contrato estándar de respuesta paginada en la capa API. El objetivo es que todos los listados devuelvan la misma estructura sin duplicarla en cada proyecto.

public class ListResponse<T>
{
    public IEnumerable<T>? Items { get; set; }
    public int TotalCount { get; set; }
}

TaskMessage

Model que permite consultar desde la API si una tarea en background está en curso, ha finalizado o ha fallado. Extiende Base.

public class TaskMessage<TType> : Base where TType : Enum
{
    public Guid Reference { get; set; }
    public TType? Type { get; set; }
    public string? Details { get; set; }
    public DateTime CreatedOn { get; set; }
    public DateTime StartedOn { get; set; }
    public DateTime? CompletedOn { get; set; }
    public string? Errors { get; set; }
}

User

Model que representa los datos de un usuario que el cliente necesita ver. Solo expone Name y Email. Los proyectos lo usan directamente como tipo de respuesta en los controllers, mapeado desde el DTO de Application mediante AutoMapper:

public class User : Base
{
    public string Name { get; set; } = default!;
    public string Email { get; set; } = default!;
}

[HttpGet("{id:long}")]
public ActionResult<User> Read(long id) =>
    Ok(Mapper.Map<User>(UserService.Read(id)));

Setup (Setup/)

AuthenticationSetup — Autenticación JWT

Su objetivo es configurar la autenticación JWT de forma centralizada para que todos los endpoints estén protegidos con el mismo mecanismo.

builder.Services.AddTechsBcnApiAuthentication(builder.Configuration);

{
  "Auth": {
    "PolicyName": "ApiPolicy",
    "Jwt": {
      "Issuer": "$(AuthJwtIssuer)",
      "Audience": "$(AuthJwtAudience)",
      "Key": "$(AuthJwtKey)",
      "ExpirationMinutes": 50
    }
  }
}

SwaggerSetup — Documentación

Su objetivo es generar la documentación de la API automáticamente a partir de los XML comments de los controllers.

builder.Services.AddTechsBcnApiSwagger(builder.Configuration, $"{typeof(Program).Assembly.GetName().Name}.xml");

app.UseTechsBcnSwagger();

{
  "Swagger": {
    "ApiTitle": "$(SwaggerApiTitle)",
    "ApiDescription": "$(SwaggerApiDescription)",
    "RoutePrefix": "swagger",
    "PrimaryEndpointLabel": "$(SwaggerPrimaryEndpointLabel)",
    "EnableDebugToken": false,
    "DebugRoleClaim": "$(SwaggerDebugRoleClaim)"
  }
}

Swagger:DebugRoleClaim solo es necesario cuando Swagger:EnableDebugToken es true.

ErrorMiddleware — Manejo de errores

Su objetivo es interceptar automáticamente cualquier excepción no controlada y traducirla a una respuesta HTTP con el código correcto. Al registrarlo, los controllers pueden centrarse en el flujo principal sin necesidad de bloques try/catch — si un servicio lanza una excepción, el middleware la captura y devuelve la respuesta adecuada. El contrato de respuesta de error es siempre ApiError.

app.UseMiddleware<ErrorMiddleware>();

Mapea automáticamente excepciones a códigos HTTP:

• ArgumentException, BadHttpRequestException, DataValidationException — HTTP 400
• InvalidOperationException, KeyNotFoundException, EntityNotFoundException — HTTP 404
• UnauthorizedAccessException — HTTP 401
• El resto — HTTP 500

public class ApiError
{
    public string Id { get; set; } = default!;
    public string Message { get; set; } = default!;
}

MapperProfile

Su objetivo es desacoplar la capa API de los DTOs de Application, exponiendo únicamente los datos que el cliente necesita. La conversión entre Models y DTOs se realiza mediante AutoMapper. Los proyectos no tienen que redefinir los mappings base — se incluye al configurar AutoMapper junto a los profiles propios del proyecto:

• API.ListRequest — DTOs.ListRequest
• ListResponse<T> — API.ListResponse<T>
• API.TaskMessage<TType> — DTOs.TaskMessage<TType>
• API.User — DTOs.User

services.AddMyProjectServices(
    builder.Configuration,
    cfg => cfg.AddProfile(new TechsBCN.Platform.API.Setup.MapperProfile())
);

Program.cs

Su objetivo es orquestar la inicialización de la aplicación de forma limpia, delegando toda la configuración en extensiones de la carpeta Setup.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMyProjectApiServices(builder.Configuration);

var app = builder.Build();

app.UseMyProjectApiPipeline();

await app.RunAsync();