Tutorial completo para crear una API REST profesional con ASP.NET Core

Las API REST se han convertido en la base de la comunicación entre aplicaciones modernas. Desde aplicaciones móviles hasta plataformas empresariales, una API bien diseñada permite intercambiar información de forma segura, escalable y eficiente. En este tutorial aprenderás cómo crear una API REST profesional utilizando ASP.NET Core, una de las tecnologías más potentes del ecosistema .NET.

¿Qué es una API REST?

REST (Representational State Transfer) es un estilo arquitectónico que utiliza el protocolo HTTP para permitir la comunicación entre sistemas. Una API REST expone recursos mediante URLs y utiliza métodos HTTP estándar como:

• GET: Obtener información.
• POST: Crear nuevos registros.
• PUT: Actualizar recursos existentes.
• DELETE: Eliminar registros.

Por ejemplo, una API de productos podría utilizar las siguientes rutas:

GET /api/products
GET /api/products/1
POST /api/products
PUT /api/products/1
DELETE /api/products/1

Paso 1: Crear el proyecto

Con .NET 10 instalado, puedes crear una API utilizando la CLI:

dotnet new webapi -n ProductApi
cd ProductApi

La plantilla genera automáticamente la estructura básica del proyecto, incluyendo controladores, configuración y soporte para OpenAPI (Swagger).

Paso 2: Organizar la arquitectura

Una API profesional debe mantener una estructura ordenada.

ProductApi
│
├── Controllers
├── Models
├── DTOs
├── Services
├── Repositories
├── Data
└── Program.cs

Cada carpeta tiene una responsabilidad específica:

• Controllers: Gestionan las solicitudes HTTP.
• Models: Representan entidades del negocio.
• DTOs: Objetos para transferencia de datos.
• Services: Lógica de negocio.
• Repositories: Acceso a datos.
• Data: Configuración de base de datos.

Esta separación facilita el mantenimiento y escalabilidad del proyecto.

Paso 3: Crear el modelo

Supongamos que desarrollaremos una API para administrar productos.

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public int Stock { get; set; }
}

Este modelo representa la información almacenada en la base de datos.

Paso 4: Configurar Entity Framework Core

Instala los paquetes necesarios:

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.SqlServer

Crea el contexto:

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options)
        : base(options)
    {
    }

    public DbSet<Product> Products => Set<Product>();
}

Luego registra el contexto en Program.cs:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection")));

Paso 5: Crear el controlador

Un controlador recibe las solicitudes y devuelve respuestas.

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly AppDbContext _context;

    public ProductsController(AppDbContext context)
    {
        _context = context;
    }

    [HttpGet]
    public async Task<IActionResult> GetAll()
    {
        return Ok(await _context.Products.ToListAsync());
    }
}

Con este endpoint ya es posible consultar todos los productos.

Paso 6: Agregar operaciones CRUD

Crear producto

[HttpPost]
public async Task<IActionResult> Create(Product product)
{
    _context.Products.Add(product);
    await _context.SaveChangesAsync();

    return CreatedAtAction(
        nameof(GetById),
        new { id = product.Id },
        product);
}

Obtener producto por ID

[HttpGet("{id}")]
public async Task<IActionResult> GetById(int id)
{
    var product = await _context.Products.FindAsync(id);

    if (product == null)
        return NotFound();

    return Ok(product);
}

Actualizar producto

[HttpPut("{id}")]
public async Task<IActionResult> Update(int id, Product product)
{
    if (id != product.Id)
        return BadRequest();

    _context.Update(product);
    await _context.SaveChangesAsync();

    return NoContent();
}

Eliminar producto

[HttpDelete("{id}")]
public async Task<IActionResult> Delete(int id)
{
    var product = await _context.Products.FindAsync(id);

    if (product == null)
        return NotFound();

    _context.Products.Remove(product);
    await _context.SaveChangesAsync();

    return NoContent();
}

Paso 7: Validaciones profesionales

Evita recibir datos incorrectos utilizando Data Annotations:

public class ProductDto
{
    [Required]
    [MaxLength(100)]
    public string Name { get; set; } = string.Empty;

    [Range(0.01, 999999)]
    public decimal Price { get; set; }

    [Range(0, int.MaxValue)]
    public int Stock { get; set; }
}

Esto mejora la calidad de los datos y reduce errores en producción.

Paso 8: Documentar con Swagger

Swagger permite probar la API desde el navegador.

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

Y en el pipeline:

app.UseSwagger();
app.UseSwaggerUI();

Al ejecutar la aplicación podrás acceder a una interfaz interactiva para probar todos los endpoints.

Paso 9: Implementar autenticación JWT

Las APIs modernas deben proteger sus recursos.

JWT (JSON Web Token) permite autenticar usuarios mediante tokens firmados digitalmente. Una vez configurado, cada petición deberá incluir:

Authorization: Bearer TOKEN

Esto garantiza que solo usuarios autorizados puedan acceder a determinados recursos.

Paso 10: Manejo global de errores y logging

Una API profesional debe registrar errores y responder de forma consistente.

app.UseExceptionHandler("/error");

Además, ASP.NET Core integra soporte para logging que puede conectarse con herramientas como Application Insights, Serilog o Elastic Stack.

Buenas prácticas finales

• Utiliza DTOs en lugar de exponer entidades directamente.
• Implementa inyección de dependencias.
• Versiona tu API.
• Protege los endpoints con JWT.
• Documenta todo con Swagger/OpenAPI.
• Utiliza Entity Framework Core o Dapper según las necesidades del proyecto.
• Implementa pruebas unitarias e integración.
• Sigue principios SOLID y arquitectura limpia.

Crear una API REST profesional con ASP.NET Core va mucho más allá de exponer algunos endpoints. Una solución empresarial requiere una arquitectura organizada, validaciones, seguridad, documentación y buenas prácticas de desarrollo. Gracias al rendimiento, escalabilidad y herramientas integradas de ASP.NET Core, es posible construir APIs modernas capaces de soportar desde pequeños proyectos hasta sistemas corporativos de gran escala. Con estos fundamentos tendrás una base sólida para desarrollar servicios robustos, mantenibles y preparados para producción.