ASP.Net Web API – Meu primeiro serviço REST

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.

ASP.Net Web API

Escolha o Template do ASP.Net Web API.

ASP.Net Web API

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

ASP.Net Web API

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).

ASP.Net Web API

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)

ASP.Net Web API

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.

ASP.Net Web API

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.

ASP.Net Web API

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.

ASP.Net Web API

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

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

55 pensou em “ASP.Net Web API – Meu primeiro serviço REST

  1. Artigo muito bom… estou a pouquíssimo tempo na área e estou adorando seu material, bem fácil de entender

  2. Quero criar serviços mais estou com uma dúvida sobre qual api usar. Existem limitações de segurança do web api quanto ao wcf?

    • Olá Andrey,

      Se vc for criar um serviço para comunicação externa vá de WebAPI, no caso de interna prefira WCF, mas depende do que precisa fazer.
      No WebAPI vc precisa configurar toda a segurança mas dá para deixar bem seguro sim.

      Abs!

  3. Muito bom seu post, Tenho uma duvida.

    Sou novo no mundo da programacao.
    Se eu montar um webservice com WPF no c#, eu consigo hospedar e se comunicar tambem com aplicativos mobile?

    Exemplo : se eu contratar uma hospedagem aspnet na local web, eu consigo hospedar o webservice como se fosse um site?

    Vlw

    • Olá Ricardo,

      Vc pode fazer isso com WCF sim, porém verifique se o REST com WebAPI não lhe atende melhor nesse caso.

      Em ambos os casos a maioria dos hosts lhe deixarão fazer isso sim.

      Abs!

  4. Ótimo artigo mas tenho uma pergunta. (não envolve muito o artigo)

    Se eu criar um app utilizando um WebAPI e algum usuário mais curioso do app conseguir descobrir o endereço do WebAPI, o mesmo poderá utilizar todos os recursos ali contidos certo?! Apenas fazendo a chamada … Existe alguma forma de travar isso e fazer o acesso ser restrito apenas ao app?

    Levando em consideração que se for um usuário mais ‘experiente’ e o mesmo poder ter a capacidade de obter acesso ao código fonte (no caso do android por exemplo, isto também ja descartaria uma possível solução que seria uma chave enviada do app para o webAPI como forma de autenticação)

    Obrigado!

      • Diogo e Leonardo, estou implementando um WebService, o qual gerou precisamente a mesma discussão. A melhor solução que cheguei até o momento foi adotar 3 mecanismos de segurança:
        1 – Toda a comunicação deve ser por HTTPS!
        2 – Validar de onde vem a requisição (por IP no nosso caso, mais isto não é 100% seguro, uma vez que é possível simular um IP fake, embora seja difícil).
        3 – Criar uma chave de acesso para a aplicação.

        Acredito que com pelo menos os itens 1 e 3 você já tem uma boa segurança, pois um complementa o outro (a sua comunicação é encriptada, e ao mesmo tempo você tem uma chave secreta que é necessária para a execução do método e que não será conhecida por um interceptador do seu tráfego). A ação 2 é apenas mais um reforço, que dependendo da aplicação nem seria possível… Não sei se isto é um padrão, mas foi a melhor solução até o momento… Espero ter ajudado.

        • Boa noite galera,

          Para sanarem esta dúvida, leiam um pouco a respeito de User Access Level (Nível de acesso de usuário) e dêem uma olhada no Google OAuth 2.0

  5. Excelente, muito didático, enfatiza pontos e conceitos importantes.
    Parabéns!
    Agora “aleister@therion” foi sensacional kkkkkkk muito bom gosto

  6. Ótimo artigo Eduardo, parabéns! Estou no aguardo dos demais artigos, principalmente envolvendo segurança com Autenticação e Autorização! Abraços

  7. Eduardo, você teria um exemplo de consumo de WEBAPI ? montei uma e a aplicação que eu quero que receba as informações esta recebendo o retorno em json porem não consigo transformar esse retorno em um objeto para que eu possa pegar o que quero

    • Olá, eu não manjo muito. Mas já que o retorno é uma string, que tal você armazenar num vetor? E quando for utilizar só colocar a posição. Isso é possível ou eu to viajando?

  8. Muito bom o Artigo! Parabéns!!!
    Teria algo de como “publicar” o web API em servidor Apcahe ou IIS?

  9. Muito bom, estou começando a trabalhar com API agora.
    Para o primeiro exemplo tranquilo e muito bom, parabéns.
    Eu preciso passar um WCF para webAPI.
    E agora? rs!

  10. Gostei do artigo Pires, você foi claro e deu para captar a idéia dessa tecnológica, e a diferença dos protocolos, obrigado.

  11. Cara,
    Depois de um artigo deste tive que responder aqui.

    Excelente publicação.
    Parabéns mesmo!

    Consegui entender graças a seu artigo.

    Abraços e continue postando!

  12. Muito bom esse post, parabéns pelo seu trabalho. Bom, preciso que tire uma duvida: estou fazendo um projeto que mistura um pouco esse post com com o post “Tutorial ASP.NET MVC 5 + DDD + EF + AutoMapper + IoC + Dicas e Truques”, que seria um projeto incrementando o outro. Chegue num ponto que começou a dar um erro na hora de colocar o construtor na ApiController onde eu tento chamar IEmpresaAppService (do jeito que você faz no outro projeto). Como eu faço esse construtor?
    (erro no navegador: This XML file does not appear to have any style information associated with it. The document tree is shown below.)

  13. Boa tarde, Eduardo.

    Não consegui fazer o download do e-Book gratuito sobre ASP.Net Web API, o link aparenta estar quebrado. Pode me passar um novo link para download?

    Obrigaod.

Os comentários estão fechados.