Add API Endpoints

Add API Endpoints (Query.Api / Upload.Api)

Scope

This skill applies only to Query.Api and Upload.Api. Do not modify Workers (Transcription, Embedding) or Shared.

Architecture Overview

Pattern 1: Upload.Api (Interface + UseCase)

Upload.Api uses thin controllers that delegate to services via interfaces.

1. Add DTOs in Domain/DTOs/

namespace Upload.Api.Domain.DTOs
{
    public class YourResponseDto
    {
        public Guid Id { get; set; }
        public string Name { get; set; } = string.Empty;
        // ...
    }
}

2. Add method to interface in Application/Interfaces/

namespace Upload.Api.Application.Interfaces
{
    public interface IUploadService  // or IYourService
    {
        Task<YourResponseDto?> YourMethodAsync(Guid id, CancellationToken ct);
    }
}

3. Implement in UseCase (or create new UseCase)

UseCase lives in Application/, implements the interface, and uses:

• UploadDbContext for persistence
• IEventPublisher for RabbitMQ (only when publishing events)
• IFileStorageFacade for file operations (when applicable)
• ILogger<T> for logging

4. Add controller action

Controller must:

• Inject the service via constructor
• Validate input before calling the service
• Return ActionResult with the created DTO (Ok, NotFound, BadRequest, Accepted, StatusCode)
• Use ErrorResponseRequest for 4xx when appropriate
• Catch exceptions and return 500 with generic error (do not expose stack traces)
• Pass CancellationToken to async calls

[HttpGet("{id}/your-action")]
public async Task<ActionResult<YourResponseDto>> YourAction(Guid id, CancellationToken ct)
{
    var result = await _uploadService.YourMethodAsync(id, ct);
    if (result == null)
        return NotFound(new { error = "Recurso não encontrado" });
    return Ok(result);
}

5. Register in Program.cs

builder.Services.AddScoped<IUploadService, UploadMediaUseCase>();
// Or new service:
// builder.Services.AddScoped<IYourService, YourUseCase>();

Pattern 2: Query.Api (Controller + Facade)

Query.Api uses facades to orchestrate infrastructure; controllers stay thin.

1. Add request/response models in Application/

Place in QueryModels.cs or a dedicated file (e.g. YourFeatureModels.cs):

namespace Query.Api.Application
{
    public class YourRequest
    {
        public string Param { get; set; } = string.Empty;
    }

    public class YourResponse
    {
        public string Result { get; set; } = string.Empty;
    }
}

2. Add method to Facade

RagFacade or a new facade orchestrates:

• EmbeddingGeneratorService
• TranscriptionSegmentVectorSearchRepository
• GenerateAnswerUseCase
• IConfiguration

3. Add controller action

Controller must:

• Inject the facade
• Validate input (e.g. string.IsNullOrWhiteSpace)
• Return ActionResult<T> or IActionResult
• Catch exceptions and return 500 with generic message

[HttpPost("your-route")]
public async Task<ActionResult<YourResponse>> YourAction([FromBody] YourRequest request)
{
    if (string.IsNullOrWhiteSpace(request.Param))
        return BadRequest("Param não pode estar vazio.");

    try
    {
        var response = await _ragFacade.YourMethodAsync(request);
        return Ok(response);
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Erro interno: {ex.Message}");
    }
}

4. Register in Program.cs

Facade and its dependencies are already registered; add new ones if needed:

builder.Services.AddScoped<YourNewService>();

Conventions

Controller

• [ApiController] and [Route("api/[controller]")] on class
• Route params: [HttpGet("{id}/status")], [HttpPost]
• Body: [FromBody] RequestType request
• Query: [FromQuery] string? param
• Always pass CancellationToken ct for async actions

Validation

• Validate required fields in controller before calling service
• Return BadRequest with clear message or ErrorResponseRequest
• Use NotFound when entity is missing

Error handling

• Upload.Api: new ErrorResponseRequest("message") for 4xx
• Do not expose internal details in 500 responses
• Log errors with ILogger where useful

Layering (AGENTS.md)

• Domain → pure models, DTOs, enums
• Application → controllers, use cases, facades, interfaces
• Infrastructure → DbContext, repositories, AI, messaging

Checklist

Before finishing, verify:

• DTOs/models in correct namespace and folder
• Interface extended (Upload) or facade extended (Query)
• Controller validates input and handles null/errors
• CancellationToken passed through async chain
• New services registered in Program.cs if needed
• No synchronous coupling between services (event-driven)
• Minimal, localized edits; no refactoring unrelated code

Converted and distributed by TomeVault — claim your Tome and manage your conversions.