Recentemente, Oren Eini (Ayende) publicou um post analisando o código de parte de uma API que continha uma falha grave de design. Nesse post, reproduzimos algumas das ideias que ele compartilhou e adicionamos algumas considerações que consideramos relevantes.

[Route("/public/api/v1/tickets/{org}")]
public async Task<IActionResult> Get(string org, int skip = 0) 
{
    var tickets = await session.Query<Domain.SupportTicket>()
        .Where(x=>x.Organization == org)
        .OrderByDescending(x => x.LastUpdate)
        .Skip(skip)
        .ToListAsync();
    
    return Ok(tickets);
}

O problema de design apontado por Oren é a exposição de um objeto de domínio em uma API pública (feita para ser consumida em aplicações desenvolvidas por outros times, fora da empresa). Essa, aliás, é uma dívida técnica extremamente comum contraída, geralmente, por inocência ou falta de conhecimento.

Um dos maiores problemas de expor um objeto de domínio em uma API pública é o acoplamento. Como Oren destaca, tal decisão vincula, para começar, o versionamento do domínio ao versionamento da API e, eventualmente, mudanças no domínio  com potencial para tornar código consumidor incompatível podem “passar” de forma inadvertida.

Outro problema a considerar é o potencial vazamento de dados sensíveis. Afinal, é normal que objetos de domínio sejam “enriquecidos” na medida que o projeto avança.

Um problema adicional, em nossa análise, é que o acoplamento resultante da exposição de objetos de domínio direciona o desenvolvimento para monolíticos distribuídos.

A recomendação de Oren foi criar um modelo exclusivamente para compartilhamento da API. Além disso, ele recomendou a não utilização de bibliotecas de mapeamento como o Automapper. Segundo ele, é importante evitar qualquer chance de exposição acidental.

[Route("/public/api/v1/tickets/{org}")]
public async Task<IActionResult> Get(string org, int skip = 0)
{
    var tickets = await session.Query<Domain.SupportTicket>()
        .Where(x=>x.Organization == org)
        .OrderByDescending(x => x.LastUpdate)
        .Skip(skip)
        .Select(ticket => new PublicTicketDto
        {
          Subject = ticket.Subject,
          LastUpdate = ticket.LastUpdate,
          Status = ticket.Status,
          // etc
        })
        .ToListAsync();
    return Ok(tickets);
}

Na EximiaCo, defendemos a categorização de APIs como internas ou externas. Nossa experiência é que APIs de propósito geral costumam gerar baixa adesão, além de outros prejuízos (como aumento de consumo da rede e requisições desnecessárias).

A categorização de APIs como propomos é um exemplo de como decisões arquiteturais mitigam os riscos de decisões ruins de design como a que estamos tratando nesse post.

Dissemos, no passado, que nem tudo que parece divida técnica, efetivamente, é. Entretanto, nesse caso, temos um problema oposto – uma dívida técnica que é difícil de ser percebida como tal.

Os “juros” dessa dívida técnica podem levar muito tempo para serem percebidos. Mas, quando finalmente a “cobrança” acontece, podem ter impactos difíceis de absorver.