ASP.Net Web API é um framework que facilita a construção de serviços REST HTTP que alcançam uma grande variedade de clientes incluindo Mobile, Browsers e aplicações locais. É a plataforma ideal para construção de serviços REST baseados em .Net

Com o lançamento do ASP.Net MVC 4 em 2012 uma das novas features foi o ASP.Net Web API, entenda como funciona e aprenda a criar sua primeira aplicação HTTP REST.

Introdução

Serviços de internet são populares já faz um bom tempo, WebServices foram desenvolvidos e consumidos durante longos anos sendo uma tecnologia livre de plataforma, ou seja, aplicações .Net e Java se comunicam por WebServices sem dependência de tecnologias. Nos anos seguintes a Microsoft lançou o Remoting e por fim o famoso WCF que engloba (HTTP, TCP, MQ).

Apesar do Remoting e WCF serem tecnologias Microsoft o que WebServices, Remoting e WCF tem em comum? Todos eles são baseados em SOAP (Simple Object Access Protocol). O SOAP é baseado em XML e busca padronizar o conteúdo que é trafegado entre as pontas. O problema do SOAP é que algumas plataformas não conseguiram acompanhar sua evolução e a adoção se tornou complicada devido sua implementação, por este motivo começaram a surgir soluções alternativas mais simples.

Uma solução alternativa ao SOAP e altamente adotada é o REST (Representational State Transfer), baseado totalmente em HTTP e seus recursos. Para o melhor entendimento sobre ASP.Net Web API e REST sugiro conhecer um pouco sobre o protocolo HTTP.

Grandes empresas como Google, Facebook, LinkedIn, Netflix entre diversas outras já disponibilizam APIs Web para serem consumidas, todas elas são baseadas em HTTP com REST.

O ASP.Net Web API utiliza HTTP com REST e diferente do SOAP não depende de XML para trafegar as informações, o formato padrão para isso é JSON (Java Script Object Notation).

JSON é um formato amplamente utilizado em qualquer plataforma (não apenas .Net),  é um subconjunto da notação de objeto de JavaScript, mas seu uso não requer JavaScript exclusivamente. Isso proporciona um potencial muito grande para os serviços HTTP, pois é um formato intercambiável, leve e livre de plataformas.

É possível retornar XML com Web API ao invés de JSON ou outros formatos como CSV. Também é possível criar um formato próprio para retornar os dados, tudo fica a critério do desenvolvedor.

Mão na massa

Vamos iniciar a construção do nosso serviço REST com ASP.Net Web API, para isso este exemplo irá utilizar o Visual Studio 2012. Crie um novo projeto Web ASP.Net MVC 4.

Escolha o Template do ASP.Net Web API.

Espere seu projeto ser criado e será exibida esta tela inicial (clique para expandir).

Note que apesar de ser um template para construção de serviços o projeto não deixa de ser ASP.Net MVC, no caso da criação de um projeto MVC + Web API não é necessário ter dois projetos na mesma solution, utilize apenas o template ASP.Net Web API.

Rodando pela primeira vez a aplicação (F5).

Uma Web Application no layout padrão do ASP.Net MVC 4 foi criada, você pode utilizar este site para criar a documentação e apresentação de sua Web API.

Com o projeto configurado a proposta é construir um serviço de consumo do cadastro de clientes, o serviço irá realizar consultas no modelo de dados que iremos criar.

Na pasta Model adicione uma nova classe chamada Cliente.

public class Cliente
{
    public int ID { get; set; }

    public string Nome { get; set; }

    public string Email { get; set; }

    public bool Ativo { get; set; }
}

Na sequência crie uma Controller para trabalhar com a classe de Clientes (clique direito na pasta Controller > Add > Controller)

Observe que nesse exemplo está sendo utilizada uma opção de Scaffolding para criar uma Controller de Web API vazia, porém com as actions de leitura e escrita, caso estivéssemos utilizando Entity Framework a opção acima da selecionada já criaria uma estrutura com o CRUD e etc…

Com a Controller criada eis o código gerado.

using System.Collections.Generic;
using System.Web.Http;

namespace MeuServicoWebAPI.Controllers
{
    public class ClienteController : ApiController
    {
        // GET api/cliente
        public IEnumerable Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/cliente/5
        public string Get(int id)
        {
            return "value";
        }

        // POST api/cliente
        public void Post([FromBody]string value)
        {
        }

        // PUT api/cliente/5
        public void Put(int id, [FromBody]string value)
        {
        }

        // DELETE api/cliente/5
        public void Delete(int id)
        {
        }
    }
}

Total semelhança com MVC certo? Digo inclusive que é mais fácil construir uma Web API do que uma WebApp com MVC.

Como diferenciar uma Controller MVC de uma Controller Web API?
Uma Controller Web API herda de ApiController enquanto uma Controller MVC herda de Controller. Essa é a forma mais fácil de identificar.

Um ponto importante, o MVC assim como o Web API possuem rotas pré-definidas, no template de projeto a rota do MVC fica no arquivo RouteConfig.cs enquanto a do Web API fica no arquivo WebApiConfig.cs, ambas na pasta App_Start.

Observe as duas rotas.

// Rota Web API
config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );

// Rota MVC
routes.MapRoute(
                name: "Default",
                url: "{controller}/{action}/{id}",
                defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional }
            );

Existem algumas diferenças, mas a que é mais importante de entender é que no caso da rota MVC a sequencia padrão será {controller}/{action}/{id} já na rota Web API a sequência é api/{controller}/{id}, sendo que “api” é um valor hard coded e não temos uma action configurada para ser chamada na URI.

Sendo assim como a rota do Web API sabe qual método está sendo chamado?

É um ponto muito importante a entender, por convenção do ASP.Net Web API os nomes dos métodos expressam a ocasião em que eles serão chamados. Dado os métodos da Controller acima:

• Get
• Post
• Put
• Delete

Estes são os nomes dos métodos e também são alguns dos verbos aceitos pelo HTTP, falando em HTTP para os verbos listados teríamos os seguintes comportamentos:

• Get = Select
• Post = Insert
• Put = Update (ou Insert)
• Delete = Delete

Ou seja, através do HTTP quando for realizado um GET via URI o Web API retornará o resultado do método Get, um POST via formulário o Web API fará uma inclusão através do metodo Post, PUT via formulário uma alteração através do método Put e DELETE via URI uma exclusão através do método Delete.

Vale lembrar que isso é uma convenção e podemos fazer de outras formas, por exemplo, o método Get poderia ser GetClientes, funcionaria da mesma forma, pois inicia com Get.
Se um método for criado como RetornarClientes seria necessário especificar qual verbo HTTP este método aceita, uma vez que o Web API não reconheceria sozinho qual dos métodos executar, nesse caso ficaria assim:

// Definindo qual o verbo o método aceita.
[AcceptVerbs("GET")]
public IEnumerable RetornarClientes()
{
    return new string[] { "value1", "value2" };
}

Especificando o tipo de verbo aceito no método podemos definir livremente a nomenclatura a ser utilizada sem depender da convenção padrão.

Atenção, cuidado ao definir os verbos aceitos, pois se um método tiver a mesma estrutura (mesmo verbo aceito e mesmo tipo de parâmetros recebidos) irá resultar em uma exception, pois o Web API não saberá qual dos métodos deverá executar.

Partindo da estrutura da Controller gerada faremos ela trabalhar com o modelo de dados da classe Cliente.

using System.Linq;
using System.Web.Http;
using MeuServicoWebAPI.Models;

namespace MeuServicoWebAPI.Controllers
{
    public class ClienteController : ApiController
    {
        private readonly Cliente[] Clientes = new Cliente[]
                {
                    new Cliente { ID = 1, Nome = "Eduardo Pires", Email = "[email protected]", Ativo = true },
                    new Cliente { ID = 2, Nome = "Bill Gates", Email = "[email protected]", Ativo = true },
                    new Cliente { ID = 3, Nome = "Aleister Crowley", Email = "[email protected]", Ativo = false }
                };

        // GET api/cliente
        public Cliente[] Get()
        {
            return Clientes;
        }

        // GET api/cliente/5
        public Cliente Get(int id)
        {
            var clientes = Clientes;

            return clientes.SingleOrDefault(x => x.ID == id);
        }

        // POST api/cliente
        public void Post([FromBody]string value)
        {
        }

        // PUT api/cliente/5
        public void Put(int id, [FromBody]string value)
        {
        }

        // DELETE api/cliente/5
        public void Delete(int id)
        {
        }
    }
}

*Para os métodos diferentes de Get (Post, Put, Delete) seria necessária uma estrutura de gravação de dados que não será abordada nesse exemplo.

Executando a aplicação testaremos a chamada do serviço ASP.Net Web API.
Primeiramente será chamado o método Get para testar se o serviço retornará toda a lista de clientes. Observe a URI no browser.

O serviço funcionou e respondeu sendo chamado pelo browser, o retorno foi em XML, pois o browser não interpreta JSON, por padrão o Web API está configurado para responder JSON sempre que possível.

Para testar com mais detalhes usaremos uma ferramenta chamada Fiddler (recomendo fortemente o conhecimento e uso desta ferramenta).

Nesse exemplo será chamado o método Get que aceita o parâmetro Id e retornará um dado de cliente específico através de uma pesquisa executada no método. Primeiramente chamaremos o serviço Web API através da aba Composer, note que o verbo escolhido é o Get e que agora está sendo informado o valor do Id do cliente na URI do serviço. Clicando no botão Execute será feita a chamada.

Na coluna da direita é possível observar que a consulta foi feita e o retorno dela é o código HTTP 200 (OK). Clicando no item desta coluna observe o retorno em JSON que será exibido pela ferramenta.

O serviço retornou um dado de cliente específico para esta consulta. Para ter uma visão completa do retorno clique na aba Raw, localizada ao lado da aba JSON.

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.30319
X-SourceFiles: =?UTF-8?B?RDpcTGFic1xNZXVTZXJ2aWNvV2ViQVBJXE1ldVNlcnZpY29XZWJBUElcYXBpXGNsaWVudGVcMg==?=
X-Powered-By: ASP.NET
Date: Thu, 11 Jul 2013 03:58:17 GMT
Content-Length: 71
{"ID":2,"Nome":"Bill Gates","Email":"[email protected]","Ativo":true}

A última linha é o retorno JSON da consulta em texto puro sem a formatação da ferramenta, observe que é muito mais simples que XML.

O serviço Web API está funcionando e retornando uma lista de clientes ou um cliente específico através de seu ID, basta agora ser consumido por qualquer tipo de aplicação.

Para aprender mais

Recentemente o Israel Aece lançou um e-Book gratuito sobre ASP.Net Web API, faça o download dele aqui. Recomendo a leitura.

O site oficial do ASP.Net Web API também possui diversos exemplos e tutoriais essenciais no aprendizado.

Resumo

Podemos observar que é muito simples criar um serviço REST HTTP utilizando ASP.Net Web API e para quem está habituado com ASP.Net MVC é mais simples ainda.

A ferramenta Fiddler ajuda muito em testes, podemos observar com riqueza os valores retornados e os códigos de HTTP, muito útil no caso de uma análise.

Continue acompanhando os posts da série, no próximo sobre Web API abordarei segurança com Autenticação e Autorização e exemplos de um site consumindo o retorno em JSON do serviço Web API.

Referências

• ASP.Net Web API – Web Site Oficial

Gostou do artigo? Comente e compartilhe suas impressões nos comentários abaixo 😉