Implementando API com ASP.NET Core 2.1 — Parte 1
Hoje vamos aprender a implementar uma API simples.
ASP.NET Core é uma versão cross-plataform e open-source do .NET framework, utilizado para desenvolvimento de serviços REST baseados em nuvem. Esse serviços são expostos para serem consumidos através de requisições HTTP ou HTTPS.
O cliente (softwares que consomem as APIs) que irá consumir o serviço, pode ser um aplicativo mobile, desktop, página web entre outros.
Na primeira parte, vamos criar uma API que que retornará nomes de alguns estados brasileiros.
Para os exemplos, é utilizado o Visual Studio 2017. Caso ainda não possua, segue o link para download da versão Community:
Abra o VS 2017 e clique em File > New > Project;
Selecione as opções Visual C# > .NET Core > ASP.NET Core Web Applications;
Informe o nome da aplicação, localização onde será criado o projeto (opcional) e clique em OK;
Uma nova janela será exibida com algumas opções. Certifique-se de utilizar o ASP.NET Core 2.1 e desmarque a opção “Configure for HTTPS”, conforme exemplo abaixo:
Dentre as várias opções, destacamos duas específicas, que são a Empty e API. Na primeira opção, o projeto é criado sem qualquer tipo de template, ou seja, você terá que implementar a API manualmente. Na segunda opção, é criado um projeto utilizando um template padrão, ou seja, será criado uma API de exemplo, pronta para uso. Escolha a opção Empty e clique em OK.
Após o Visual Studio terminar de criar o projeto, temos a seguinte estrutura:
Vamos agora adicionar uma pasta como nome “Controller”.
Clique sobre o nome do projeto, botão direito do mouse e clique em Add > New Folder e coloque o nome mencionado acima na pasta.
Em seguida vamos criar uma nova classe dentro dessa pasta que representa nossa controller.
Clique com o botão direito do mouse sobre o nome da pasta que você acabou de criar, clique em Add > Class e dê o nome “EstadoController”. A estrutura deverá ficar conforme segue imagem abaixo:
Alguns pontos importantes que devem ser ressaltados:
- Controller são classes que expõe métodos no qual recebem e processam as requisições em nossas aplicações. No controller é onde fica exposto todos os serviços disponíveis da nossa aplicação.
- Por convenção, todo arquivo .cs que representa um controller possui seu nome finalizado com “Controller”. No exemplo temos o EstadoController.cs, mas se quisessemos criar um novo controle devemos nomea-lo assim: “NomeApiController”.
- Startup.cs é onde fica contida a inicialização do nosso software.
Vamos agora, iniciar a implementação dos dados a serem retornados. Lembrando que para o exemplo, será feita da forma mais simples possível para o entendimento, portanto não há uma preocupação com a organização do código.
Vamos criar uma nova pasta em nosso projeto. Clique sobre o nome do projeto, botão direito do mouse e clique em Add > New Folder e coloque o nome “Dto”.
Em seguida vamos criar uma nova classe dentro dessa pasta, para isso, clique com o botão direito do mouse sobre a pasta que você acabou de criar, clique em Add > Class e dê o nome “EstadoDto”.
A estrutura deverá ficar conforme a imagem:
Vamos para a implementação da classe “EstadoDto”, que é a responsável por conter as informações do estado, portanto sua estrutura deve ser a seguinte:
Vamos agora para nosso controller, onde devemos criar um novo método privado que irá retornar uma lista de todos os estados brasileiros. Também vamos implementar nossos dois métodos GET, o primeiro busca todas as informações de todos os estado e o segundo retorna somente o estado com o id solicitado.
Abaixo temos nossa estrutura de classe a ser utilizado:
Perceba que nossa classe possui uma herança da “ControllerBase” e dois atributos que são: [ApiController] e [Route(“api/estado”)].
O ControllerBase é uma classe que disponibiliza uma série de recursos para nossa API e o atributo [ApiController] indica que a classe é exposta para receber as requisições. Geralmente o [ApiController] e o ControllerBase são utilizados em conjuntos para potencializar os recursos de nossa API.
Com nossa API pronta, vamos agora configurar nossa inicialização do projeto para que nossa controller receba as requisições. Para isso, abra o arquivo Startup.cs onde sua estrutura deverá ser a seguinte:
Em nosso arquivo Startup.cs temos dois métodos muito importantes para configuração de execução da nossa aplicação.
O ConfigureServices será executado primeiramente e nele recebemos o parametro IServiceCollection, que é um container de serviços que será disponibilizado para a aplicação. Ao adicionar serviços nele, faremos com que estes serviços estejam disponíveis em todo nosso sistema através da injeção de dependência.
Portanto precisamos adicionar o MVC framework, que é reponsável pelo mapeamento e execução das requisições, ou seja, o MVC framework é que direciona para nossa API todas as requisições recebidas em nossa aplicação. Para adicione a seguinte linha de código conforme imagem abaixo:
O método Configure será executado posteriormente ao ConfigureServices e nele configuramos como nossa aplicação deverá processar cada requisição recebida. Aqui definimos os serviços disponíveis para cada requisição recebida.
No método ConfigureServices adicionamos o MVC framework ao nosso container de serviços e nesse método Configure, vamos configurá-lo para que cada requisição utilize o MVC Framework. Para isso, vamos modificar o método conforme imagem abaixo:
Pronto! API finalizada, mas antes de realizar os testes, alguns esclarecimentos pertinentes devem ser feitos.
Repare que nossa classe EstadoController está decorada com o atributo [Router(“api/estado”)]. Esse atributo é o responsável por definir a rota em que deve ser realizado a requisição HTTP ou HTTPS.
Aí vem a pergunta:
“Mas como nossa API sabe qual método deve ser utilizado?”
Repare que cada método nosso também possui um atributo, no caso, [HttpGet] que é um protocolo de comunicação responsável por indicar a ação de leitura de dados, porém em nosso arquivo possuímos duas variantes desse atributo.
O primeiro método possui apenas [HttpGet] e não recebe nenhum parâmetro, portanto ele vai retornar uma lista com todos os estados; o segundo método possui [HttpGet(“{id}”)] e recebe o parâmetro id, onde ele retornará somente o estado que possui aquele id específico, portanto nossa API, através dessas diferenças, consegue definir o método a ser utilizado naquele momento.
Chegou o momento de testarmos tudo o que fizemos. Para isso, execute o projeto e com o endereço e portas definidas, vamos realizar uma requisição.
No meu caso a rota padrão é http://localhost:52544, porém em sua máquina a porta final pode ser diferente, portanto, se atente a isso.
Ao realizar uma requisição no seguinte endereço http://localhost:52544/api/estado, é retornado a lista de todos os estados, conforme imagem:
E por fim, ao realizar uma requisição no seguinte endereço http://localhost:52544/api/estado/1 (note que é passado o parâmetro 1) é retornado somente um estado.
Com isso, temos nossa API de leitura pronta. No próximo post, será implementado a API para persistência das informações.
Até mais!!!
