WebApiToolkit

Wissance.webapitoolkit

Este Lib ajuda a criar REST API com C# e AspNet facilmente do que escrevê -la do zero repetidamente em diferentes projetos.

1. Recursos -chave

• REST API Controller com CRUD completo contém apenas 20 linhas de código (~ 10 são importações)
  • Os métodos GET possuem suporte de paginação integrado ;
  • Os métodos GET possuem classificação e filtro embutidos por parâmetros de consulta;
• Suporte operações em massa com objetos ( Create , Update e Delete massa) em um nível de interface do controlador &&
• suporte para trabalhar com qualquer armazenamento persistente (interface IModelManager ); Bom suporte interno interno do EntityFramework (consulte a classe EfModelManager ). Consulte o App WeatherControl, que possui 2 projetos de API da Web:
  • Wissance.WeatherControl.WebApi usa EntityFramework ;
  • Wissance.WeatherControl.WebApi.V2 usa EdgeDb .

Conceitos -chave:

1. Controller é uma classe que lida com o recurso HTTP-requests para REST Resource .
2. REST Resource é igual à Entity class / Database Table
3. Todas as operações no REST Resource produzem JSON com DTO como saída. Assumimos usar apenas uma classe DTO com todos os métodos REST .

2. Contrato da API

• Aulas DTO :

  • OperationResultDto representa resultado da operação que altera os dados em dB;
  • PagedDataDto representa parte (página) dos mesmos objetos (qualquer tipo);

• Classes Controllers - classes abstratas

  • Controlador de leitura básica ( BasicReadController ) contém 2 métodos:
    • GET /api/[controller]/?[page={page}&size={size}&sort={sort}&order={order}] para obter PagedDataDto<T> Agora também temos possibilidade de enviar qualquer número de parâmetros de consulta , você só precisa passar a função para EfModelManager ou o seu próprio caminho. Também passamos a classificação (nome da coluna) && Order ( asc ou desc ) para as classes do gerente, EfModelManager permite classificar por qualquer coluna . Infelizmente aqui temos uma desvantagem única - devemos substituir as informações Swagger para mostrar o uso dos parâmetros de consulta !!! A partir de 1.6.0 é possível ver todos os parâmetros em Swagger e usá -los.
    • GET /api/[controller]/{id} para obter um objeto por id
  • Full CRUD Controller ( BasicCrudController ) = Controlador de leitura básica ( BasicReadController ) + Create , Update e Delete operações:
    • POST /api/[controller] - Para nova criação de objetos
    • PUT /api/[controller]/{id} - para editar objeto por id
    • DELETE /api/[controller]/{id} - para excluir objeto por id
  • CRUD completo com operações em massa (operações em vários objetos de uma só vez), classe base - BasicBulkCrudController = Basic Read Controller ( BasicReadController ) + Operações de BulkCreate , BulkUpdate e BulkDelete :
    • POST /api/bulk/[controller] - para criação de novos objetos
    • PUT /api/bulk/[controller] - Para editar objetos que passam em um corpo de solicitação
    • DELETE /api/bulk/[controller]/{idList} - Para excluir vários objetos por id.

  As classes dos controladores esperam que todas as operações sejam executadas usando as classes do gerente (cada controlador deve ter seu próprio gerente)

• Classes de gerentes - classes que implementa a lógica de negócios do aplicativo

  • IModelManager - Interface que descreve operações básicas
  • EfModelManager - é uma classe abstrata que contém a implementação de operações Get e Delete
  • EfSoftRemovableModelManager é uma classe abstrata que contém a implementação de operações Get e Delete com modelos removíveis SOFT ( IsDeleted = true Means Model foi removido)

Exemplo de quão mais rápido vs não-bulk:

 Elapsed time in Non-Bulk REST API with EF is 0.9759984016418457 secs.
Elapsed time in Bulk API with EF is 0.004002094268798828 secs.

Como resultado, obtivemos quase ~ 250 x API mais rápido.

3. Requisitos

Existe apenas um requisito : todas as classes de entidade para qualquer armazenamento de persistência que use com controladores e gerentes devem implementar IModelIdentifiable<T> de Wissance.WebApiToolkit.Data.Entity . Se este kit de ferramentas deve ser usado com EntityFramework , você deve derivar seu gerente de recursos do EfModelManager , ele possui métodos internos para:

• get many itens
• get one item by id
• delete item by id

4. Algoritmo de uso do kit de ferramentas com entidade

Exemplo completo é mencionado na Seção 6 (veja abaixo). Mas se você estiver começando a criar uma nova API REST Resource você deve fazer seguintes:

1. Crie uma classe DTO model ( entity ) que implementa a representação IModelSoftRemovable IModelIdentifiable<T>

 public class BookEntity : IModelIdentifiable < int >
{
    public int Id { get ; set ; }
    public string Title { get ; set ; }
    public string Authors { get ; set ; } // for simplicity
    public DateTimeOffset Created { get ; set ; }
    public DateTimeOffset Updated { get ; set ; }
}

public class BookDto
{
    public int Id { get ; set ; }
    public string Title { get ; set ; }
    public string Authors { get ; set ; } 
}

2. Crie uma função de fábrica (por exemplo, função estática de uma classe estática) que converte Model em DTO , ou seja,:

 public static class BookFactory
{
    public static BookDto Create ( BookEntity entity )
    {
        return new BookDto
        {
            Id = entity . Id ,
            Title = entity . Title ,
            Authors = entity . Authors ;
        } ;
    }
}

3. Crie a interface IModelContext que tenha a BookEntity como uma DbSet e sua classe de implementação que também deriva do DbContext ( EF Abstract Class ):

 public interface IModelContext
{
    DbSet < BookEntity > Books { get ; set ; }
}

public MoidelContext : DbContext < ModelContext > , IModelContext
{
    // todo: not mrntioned here constructor, entity mapping and so on
    public DbSet < BookEntity > Books { get ; set ; }
}

4. Configure para injetar ModelContext como um DbContext via DI , veja a classe de inicialização
5. Criar aula Controller e um par de turmas, ou seja, considere aqui CRUD completo

 [ ApiController ]
public class BookController : BasicCrudController < BookDto , BookEntity , int , EmptyAdditionalFilters >
{
    public BookController ( BookManager manager )
    {
        Manager = manager ;  // this is for basic operations
        _manager = manager ; // this for extended operations
    }
    
    private BookManager _manager ;
}

public class BookManager : EfModelManager < BookEntity , BookDto , int , EmptyAdditionalFilters >
{
    public BookManager ( ModelContext modelContext , ILoggerFactory loggerFactory ) : base ( modelContext , BookFactory . Create , loggerFactory )
    {
        _modelContext = modelContext ;
    }
    
    public override async Task < OperationResultDto < StationDto > > CreateAsync ( StationDto data )
    {
        // todo: implement
    }
    
    public override async Task < OperationResultDto < StationDto > > UpdateAsync ( int id , StationDto data )
    {
        // todo: implement
    }
    
    private readonly ModelContext _modelContext ;
}

Último parâmetro genérico no exemplo acima - EmptyAdditionalFilters é uma classe que contém parâmetros adicionais para pesquisa para ver em swagger, basta especificar uma nova classe que implementa IReadFilterable IE:

 public class BooksFilterable : IReadFilterable
{
    public IDictionary < string , string > SelectFilters ( )
    {
            IDictionary < string , string > additionalFilters = new Dictionary < string , string > ( ) ;
            if ( ! string . IsNullOrEmpty ( Title ) )
            {
                additionalFilters . Add ( FilterParamsNames . TitleParameter , Title ) ;
            }

            if ( Authors != null && Authors . Length > 0 )
            {
                additionalFilters . Add ( FilterParamsNames . AuthorsParameter , string . Join ( "," , Authors ) ) ;
            }

            return additionalFilters ;
    }
        
    [ FromQuery ( Name = "title" ) ] public string Title { get ; set ; }
    [ FromQuery ( Name = "author" ) ] public string [ ] Authors { get ; set ; }
}

5. NUGET PACKET

Você pode encontrar o Nuget-Package aqui

6. Exemplos

Aqui, consideramos apenas controladores CRUD completos porque Crud completo = somente leitura + operações adicionais (Criar, atualizar, excluir) , um exemplo completo = Aplicativo completo criado com wissance.webapitoolkit pode ser encontrado aqui: https://github.com/wissance/weathercontrol

 [ ApiController ]
public class StationController : BasicCrudController < StationDto , StationEntity , int , EmptyAdditionalFilters >
{
    public StationController ( StationManager manager )
    {
        Manager = manager ;  // this is for basic operations
        _manager = manager ; // this for extended operations
    }
    
    private StationManager _manager ;
} 

 public class StationManager : EfModelManager < StationEntity , StationDto , int >
{
    public StationManager ( ModelContext modelContext , ILoggerFactory loggerFactory ) : base ( modelContext , StationFactory . Create , loggerFactory )
    {
        _modelContext = modelContext ;
    }

    public override async Task < OperationResultDto < StationDto > > CreateAsync ( StationDto data )
    {
        try
        {
            StationEntity entity = StationFactory . Create ( data ) ;
            await _modelContext . Stations . AddAsync ( entity ) ;
            int result = await _modelContext . SaveChangesAsync ( ) ;
            if ( result >= 0 )
            {
                return new OperationResultDto < StationDto > ( true , ( int ) HttpStatusCode . Created , null , StationFactory . Create ( entity ) ) ;
            }
            return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , "An unknown error occurred during station creation" , null ) ;

            }
        catch ( Exception e )
        {
            return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , $ "An error occurred during station creation: { e . Message } " , null ) ;
        }
    }

    public override async Task < OperationResultDto < StationDto > > UpdateAsync ( int id , StationDto data )
    {
        try
        {
            StationEntity entity = StationFactory . Create ( data ) ;
            StationEntity existingEntity = await _modelContext . Stations . FirstOrDefaultAsync ( s => s . Id == id ) ;
            if ( existingEntity == null )
            {
                return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . NotFound , $ "Station with id: { id } does not exists" , null ) ;
            }

            // Copy only name, description and positions, create measurements if necessary from MeasurementsManager
            existingEntity . Name = entity . Name ;
            existingEntity . Description = existingEntity . Description ;
            existingEntity . Latitude = existingEntity . Latitude ;
            existingEntity . Longitude = existingEntity . Longitude ;
            int result = await _modelContext . SaveChangesAsync ( ) ;
            if ( result >= 0 )
            {
                return new OperationResultDto < StationDto > ( true , ( int ) HttpStatusCode . OK , null , StationFactory . Create ( entity ) ) ;
            }
            return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , "An unknown error occurred during station update" , null ) ;

        }
        catch ( Exception e )
        {
             return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , $ "An error occurred during station update: { e . Message } " , null ) ;
        }
            
    }

    private readonly ModelContext _modelContext ;
}

Apenas 2 classes muito simples ^^ usando webapitoolkit

7. API de extensão

7.1 Adicione novos métodos ao controlador existente

Considere que gostaríamos de adicionar a pesquisa de métodos ao nosso controlador:

 [ HttpGet ]
[ Route ( "api/[controller]/search" ) ]
public async Task < PagedDataDto < BookDto > > > SearchAsync ( [ FromQuery ] string query , [ FromQuery ] int page , [ FromQuery ] int size )
{ 
    OperationResultDto < Tuple < IList < BookDto > , long > > result = await Manager . GetAsync ( page , size , query ) ;
    if ( result == null )
    {
        HttpContext . Response . StatusCode = ( int ) HttpStatusCode . InternalServerError ;
    }

    HttpContext . Response . StatusCode = result . Status ;
    return new PagedDataDto < TRes > ( pageNumber , result . Data . Item2 , GetTotalPages ( result . Data . Item2 , pageSize ) , result . Data . Item1 ) ;
} 

7.2 Adicione a segurança para proteger sua API

Temos um projeto adicional para proteger API com Keycloak OpenId-Connect . Passe IHttpContextAccessor para a classe Manager e verifique algo assim: ClaimsPrincipal principal = _httpContext.HttpContext.User;

8. Materiais adicionais

Você pode ver nossos artigos sobre o uso do kit de ferramentas:

• Artigo médio sobre o uso v1.0.x
• Dev.To Artigo sobre o uso v1.0.x

9. Colaboradores