Entendendo e Desenvolvendo Restful WebServices no Framework X-Gov

Autor: Mauricio Cirelli

1. Introduo

Neste documento abordaremos a estrutura da arquitetura REST (Representational State Transfer) no

desenvolvimento de servios web. Estudaremos seus funcionamentos e postulados para, ento,
desenvolvermos uma aplicao de WebService utilizando C# 2008.
Mais adiante, iremos comparar a estrutura com a arquitetura SOAP (Simple Object Access Protocol).
Criaremos um exemplo de servio web baseado em REST e discutiremos mtodos de consumo desta
aplicao e sua publicao.
Por fim veremos como aplicar os conceitos abordados dentro do cross-media e, mais especificamente,
para o projeto X-GOV.

1.1 Histrico do REST

O termo originou-se em 2000, a partir da tese de doutorado de Roy Fielding, um dos principais autores
da especificao do protocolo HTTP (Hypertext Transfer Protocol), utilizado na comunicao Web.
Os sistemas baseados em REST so denominados RESTful e devem seguir os princpios descritos por
Fielding em sua tese: "Architectural Styles and the Design of Network-based Software Architectures".

1.2 Princpios do REST

Fielding postula que o protocolo HTTP possui recursos suficientes para executar todas as transaes
Web comuns: insero, atualizao, excluso e recuperao de informaes, utilizando apenas seus
mtodos (verbs) nativos e o endereo da requisio (URI: Uniform Resource Identifier):

Nota: URL (Uniform Resource Locator) um tipo de URI

1.2.1 O protocolo HTTP

O protocolo HTTP foi criado para garantir a comunicao no ambiente Web. graas a ele que
conseguimos acessar um site. Porm, at 2000, quando Fielding definiu a arquitetura REST, esta era
praticamente a nica funo do HTTP: receber informao de um servidor localizado atravs de uma
URL ou enviar uma informao ao mesmo.
Estas atividades fazem uso de apenas 2 verbos do HTTP: GET e POST. O HTTP foi definido contendo 8
verbos:

Nota: Atualmente o HTTP possui muitos outros verbos, porm so menos utilizados e muitos no so
aceitos na maioria dos navegadores.

OPTIONS: Uma requisio do tipo OPTIONS retornar os mtodos HTTP disponveis no servidor em
questo. Na arquitetura REST, em termos de WebServices, OPTIONS nos possibilita saber quais
WebMethods (servios, funes) esto disponveis em determinada URI.

HEAD:
Requisies HEAD retornam o cabealho da resposta HTTP. Este cabealho contm informaes como:
Content-Type: tipo de dados que o servidor aceita, como XML, JSON, texto puro.
Status: indica se a requisio foi bem sucedida ou no, indicando com 200 OK em caso
afirmativo ou com outro nmero e descrio de erro.
Date: data e hora da requisio.
 Server: tipo de web Server, como Internet Information Services (IIS), Apache, entre outros.
Content-Lenght: tamanho da resposta (quantidade de caracteres).

H outras informaes menos relevantes no cabealho de uma requisio HTTP que no sero tratadas
neste documento.

GET:
Requisies do tipo GET retornam todo tipo de informao relacionada aos parmetros fornecidos.
Dentro do ambiente de WebServices, este tipo de solicitao muito usada para fazer consultas a banco
de dados. Alm de retornar estas informaes, o mtodo GET tambm retorna o cabealho da
requisio, assim como o mtodo HEAD.

POST:
Este tipo de requisio pode ser utilizada para atualizar uma informao armazenada em uma URI ou
para inserir novas informaes, dependendo dos parmetros fornecidos.
POST apenas envia uma quantidade de parmetros de dados para o servidor, sendo ele o responsvel
por interpretar e utilizar estes parmetros da maneira que quiser.
Na arquitetura REST, Fielding define que devemos utilizar o mtodo POST apenas para inserir novas
informaes.

PUT: O mtodo PUT, ao contrrio do POST, envia obrigatoriamente uma nova pgina (ou atualiza uma
se os parmetros indicarem que j existe uma pgina onde se est desejando colocar uma nova). Apesar
de soarem muito similares, POST e PUT so bastante diferentes. PUT criar ou atualizar uma pgina
que conter os dados passados pelo URI. POST passa os dados pelo URI para o servidor, que se
encarrega de fazer o que quiser com eles.
Fielding define o uso do PUT como de atualizao de dados, na arquitetura REST.

DELETE:
Este mtodo exclui a pgina indicada por determinada URI.

TRACE:
Rastreia a solicitao, sendo possvel, para o solicitante, saber o que acontece com seus dados enviados
conforme eles trafegam pela rede at chegar ao servidor de destino. especialmente importante
quando sabemos que nossa informao passar por diversos servidores intermedirios, sendo, assim,
passveis de modificaes indesejadas.

CONNECT:
Muda a rota da solicitao atual. Muito utilizada em conjunto com proxys e tneis TCP/IP para conexes
seguras (SSL).

Cada requisio gera uma resposta do servidor. Esta resposta vem codificada em elementos chamados
status-code, que so nmeros acompanhados por uma palavra, seguindo a regra:

1xx Informational: A principal 100 Continue, que indica que o client deveria continuar sua
requisio. Esta classe de status-code apenas utilizada para a comunicao Server-client, no
sendo de grande utilidade para nosso propsito;

2xx Successful: Indica que a requisio foi feita sem problemas. Utilizaremos, principalmente,
os codes 200 OK e 201 Created, sendo o primeiro utilizado em solicitaes GET, DELETE
e PUT normalmente e o segundo em solicitaes do tipo POST.
 3xx Redirection: Classe de status-code criada para indicar se uma solicitao deve ser
redirecionada para ser concluda. Isto pode ocorrer devido a uma mudana (moved) de URI ou
utilizao de servidores Proxy.

4xx Client Error: Indica que houve um erro durante a solicitao causada pelo cliente. Este erro
pode ser: 404 Not Found, 403 Forbidden, 409 Conflict, entre outros. Estes 3 sero os
mais utilizados em servios web RESTful. O primeiro indica que a URI no pde ser encontrada,
o segundo que o mtodo utilizado no permitido e o ltimo que a solicitao j existe. 409
Conflict normalmente ocorre quando tentamos usar o mtodo POST com o mesmo Request
Body mais de uma vez.

2. REST e SOAP (na viso de WebService)

Como podemos observar, o protocolo HTTP est sendo muito pouco utilizado, tendo capacidade para
executar qualquer tipo de requisio.
Isto torna desnecessria a criao de novas arquiteturas para a troca de informaes na Web (como o
SOAP), as quais tornam a conexo mais carregada de cabealhos e informaes sobre os pacotes de
respostas e requisies que esto trafegando.
Falando sobre WebServices, no caso do SOAP, a informao transmitida atravs de um documento
XML. Junto com este documento, trafegam inmeros outros documentos de especificaes, como WS-
Notification, WS-Transfer, entre muitos outros WS- (conhecidos como WS-*) que, juntos, formam a
especificao WSDL (WebService Description Language), um documento contento todas as definies de
metadados utilizados nas requisies. Tudo isto para tornar a arquitetura multiplataforma e garantir a
interoperabilidade entre os sistemas.
Quando pensamos que o HTTP um protocolo universalmente aceito e entendido por qualquer sistema,
navegador, framework ou servidor, percebemos o quanto desnecessrio trafegar tamanha quantidade
de informao.
O principal trunfo do SOAP em relao ao REST sua portabilidade dentro de diversos protocolos.
possvel fazer uma requisio SMTP ou FTP, por exemplo, utilizando SOAP. Como o REST definido e
estruturado a partir dos verbos HTTP, ele apenas atua sobre este protocolo de comunicao.
Porm, vale ressaltar que REST uma arquitetura de projeto, portanto, pode ser utilizada para qualquer
tipo de aplicao que no seja necessariamente um WebService, enquanto SOAP foi desenvolvido
especificamente para este propsito.

3. Mudana de Paradigma:

Uma aplicao RESTful exige uma certa mudana no modo de estruturar um projeto. semelhante ao
processo que sofremos quando passamos de uma lgica estruturada para uma orientada a objetos.
At hoje, costumvamos construir nossos WebServices nos baseando em quais mtodos eles possuiriam
(quais verbos eles atenderiam).
A partir disto, crivamos uma estrutura que recebia as definies dos mtodos atravs do WSDL e
chamvamos estes mtodos em nossas aplicaes.
Quando pensamos em REST, no estamos pensando nos mtodos que nosso servio web ter, pois estes
mtodos j esto definidos: so os 8 verbos do HTTP. Temos, ento, que nos focar em como utilizar
estes 8 verbos para atender nossas necessidades.

Exemplo: O HTTP no possui um verbo BuscarContasCorrentes. Se estivssemos pensando em SOAP,

a resposta mais bvia para este problema seria: Vamos declarar um WebMethod chamado
BuscarContasCorrentes e defini-lo. A partir da, o WSDL se encarrega de fazer nosso verbo ser
entendido por todos os clients. Em REST no temos esta liberdade, pois no utilizamos um WSDL. Se
pensarmos que temos o verbo GET do HTTP e um URI que podemos definir, j temos todas as
ferramentas necessrias para resolver o problema de listar as contas correntes de nosso banco.
Poderamos implementar, ento, a seguinte requisio:

GET http://www.nossobanco.com/contascorrentes

De acordo com a especificao HTTP, esta requisio nos retornar todo o contedo da URI pedida, a
qual armazena as contas correntes do banco.

Ainda no exemplo do banco, se quisssemos criar uma nova conta corrente, por definio, devemos
utilizar o verbo POST (embora PUT tambm seja possvel), com uma requisio do tipo:

POST http://www.nossobanco.com/contascorrentes
Request Body (corpo da requisio):
cliente = NomeDoCliente;
(...)

Esta requisio criar uma nova pgina com os dados do novo cliente, passados dentro do Request
Body.

Neste exemplo, a soluo parecia bvia. Imediatamente imaginaramos os verbos PUT e DELETE
entrando em ao para atualizar ou remover os dados de uma determinada conta. O importante aqui
perceber que com os 8 verbos do HTTP, podemos traduzir qualquer tipo de problema que enfrentamos,
sem ter que criar novas interfaces, novos mtodos e novas especificaes.

4. Limbo: REST Stateless, pois HTTP Stateless:

Imaginemos a seguinte situao: realizamos uma requisio passando algumas informaes. Estas so
enviadas para a pgina definida pelo URI que digitamos. Ento nosso servidor nos responde dizendo que
recebeu estas informaes.
Estas informaes no podero mais ser requisitadas. Na verdade, elas no sero armazenadas em
cache, ou algum tipo de memria do qual possamos recuper-las ou trat-las.
Ao receber estas informaes, o servidor dever estar programado para armazen-las em uma base de
dados ou session de usurio, por exemplo. Caso contrrio, elas sero perdidas, indo para o limbo. Isto
acontece devido caracterstica Stateless do HTTP e, por conseqncia, do REST.

Este ser nosso intuito quando comearmos a codificar nosso WebService. A priori receberemos as
requisies e as passaremos a um banco de dados, retornado ao usurio os resultados ou mensagens do
servidor.

5. Estruturando uma aplicao RESTful:

A partir de agora comearemos a discutir os procedimentos para modelar uma aplicao RESTful j
voltando os exemplos para o desenvolvimento do WebService. Ao final, teremos um exemplo de
WebService funcional baseado em REST.

O primeiro passo para criar uma aplicao RESTful definir quais so os problemas que nossa aplicao
ter de resolver e tentar model-los de forma a usar as definies de GET, POST, PUT e DELETE (os
principais verbos do HTTP na arquitetura REST) j discutidas.

Nosso produto final ser um WebService que recebe mensagens (pode ser de um blog, por exemplo) as
quais contm:
Texto da Mensagem: string
Nome do Usurio: string
Data: string
ID: string (para facilitar trataremos o ID como string, ao invs de int).

Definimos ento uma classe Mensagem:

public class Mensagem
{
public string ID,
Data,
Texto,
Nome;
}

Como nossas solicitaes devero retornar alguma mensagem mais compreensvel para o usurio,
vamos criar uma nova classe que contenha a mensagem em si e uma string de resposta com relao a
operao:

public class TextoMensagem

{
public string resposta;
public Mensagem msg = new Mensagem();
}

Nossa aplicao dever realizar buscas por ID e por nome, listar todas as mensagens, gravar novas
mensagens, atualizar mensagens e apagar mensagens. Iremos implementar todos este mtodos, a fim
de exemplificar toda a tecnlogia de REST incorporada ao Windows Comunication Foundation (WCF) do
.NET Framework 3.5, utilizando os dados na forma XML e na forma JSON.

Tendo definido os mtodos que nosso WebService possuir, devemos abstra-los utilizando os verbos do
HTTP. Desta forma, definimos:

Busca Por ID:

GET http://localhost/mensagem/{id}

Busca por Nome:

GET http://localhost/mensagens/{nome}

Listar mensagens:
GET http://localhost/mensagens/

Gravar Mensagem:
POST http://localhost/mensagens/

Atualizar Mensagem:
PUT http://localhost/mensagem/{id}

Apagar Mensagem:
DELETE http://localhost/mensagem/{id}

Algumas observaes antes de prosseguirmos. Como podem perseber, nossas URIs coincidem em alguns
momentos. A diferenciao quanto ao mtodo a ser empregado se dar atravs de anlise do verbo de
solicitao.
O uso de {id} e {nome} indica que estas URIs sero dinmicas, ou seja, seu contedo depender dos
valores digitados nestes espaos. Se quisermos buscar a mensagem cujo ID 14, deveremos realizar
uma solicitao do tipo GET sobre http://localhost/mensagem/14. Veremos como construir estas URIs e
analis-las em breve.

6. Windows Comunication Foundation (WCF) REST StarterKit:

Dentro do framework .NET 3.5, com Service Pack 1, possvel instalar certos templates de projetos. Um
deles o WCF REST StarterKit, que possui diversos exemplos, templates e uma nova biblioteca, todos
desenvolvidos especialmente para desenvolver RESTful WebServices. Devemos ressaltar que algo
semelhante existe dentro da plataforma JAVA. O NetBeans IDE 6.5 possui alguns modelos de servios
RESTful que podem ser remodelados. Neste documento, utilizaremos em nossos prximos passos o
Visual Studio 2008 SP1, com .NET Framework 3.5 SP1 e construiremos nossa aplicao a partir do
modelo WCF REST Singleton Service, contido no WCF REST StarterKit.
Voc pode obt-lo aqui:
http://www.codeplex.com/aspnet/Release/ProjectReleases.aspx?ReleaseId=18830

Siga o Instalation Guide para obter sucesso na instalao do StarterKit. Voc precisar compilar um
projeto aps extrair os arquivos (Web.sln) para criar a nova dll Microsoft.ServiceModel.Web.

7. Iniciando o Projeto

Crie um novo projeto baseado no template WCF REST Singleton Service a partir do Visual Studio 2008.
Alguns arquivos densamente comentados, repletos de TO DOs, sero adicionados. Para nosso
propsito, voc pode apagar todos estes cdigos, substtuindo pelos cdigos passados ao longo dos
procedimentos descritos por aqui. Em nossos exemplos, o nome da aplicao foi definido como
RESTStarterKit1.

Primeiramente, vamos definir nossos servios, suas URIs, quais verbos HTTP sero utilizados em cada
caso e que tipo de reposta JSON ou XML receberemos. Vamos primeiramente utilizar o VS2008
Refactoring Tool para renomear todas as aparies de Service1 para Service, e de IService1 para
IService, inclusive o nome do arquivo Service1.svc criado automaticamente.

Expanda o arquivo Service.svc, para editarmos Service.base.svc.cs:

using System;
using System.Collections;
using System.Collections.Generic;
using System.Runtime.Serialization;
using System.ServiceModel;
using System.ServiceModel.Web;
using System.ServiceModel.Activation;
using System.Linq;
using System.Net;
using Microsoft.ServiceModel.Web;
namespace RESTStarterKit1
{
#region Service Contracts (Uri Templates e WebMethods)
[ServiceContract]
public interface IService
{

Isto define nossa interface. A tag ServiceContract indica que os mtodos descritos dentro desta interface
fazem parte de um servio, devendo seguir um contrato, ou seja, devendo seguir as propriedades
descritas. Continuando:

#region XML APIs

[OperationContract]
[WebGet(UriTemplate = "xml/mensagem/{id}")]
Mensagem XMLGetMensagemByID(string id);

[OperationContract]
[WebGet(UriTemplate = "xml/mensagens/{nome}")]
Mensagem[] XMLGetMensagemByNome(string nome);

[OperationContract]
[WebGet(UriTemplate = "xml/mensagens")]
Mensagem[] XMLGetMensagens();

[OperationContract]
[WebInvoke(Method = "DELETE", UriTemplate = "xml/mensagem/{id}")]
string XMLDeleteMensagem(string id);

[OperationContract]
[WebInvoke(Method = "POST", UriTemplate = "xml/mensagens")]
TextoMensagem XMLPOSTMensagem(/*Mensagem msg*/);

[OperationContract]
[WebInvoke(Method = "PUT", UriTemplate = "xml/mensagem/{id}")]
TextoMensagem XMLUpdateMensagem(Mensagem msg, string id);
#endregion

Esta regio cria os mtodos que trabalharo com respostas em XML.

XML o formato de dados padro da linguagem, portanto no foi preciso especific-lo. Cada
OperationContract indica um novo WebMethod. Estes WebMethods sero chamados sempre que as
situaes descritas pelo WebGET ou WebInvoke acontecerem. WebGet utilizado sempre que a
solicitao do tipo GET. Para os demais mtodos utilizamos o atributo WebInvoke, especificando o
verbo HTTP que ser utilizado.

As URI Templates so os modelos de URI que o usurio dever requisitar, em conjunto com o tipo de
solicitao, para se utilizar dos servios. Este esquema permite um entendimento e uma estruturao
perfeitamente anlogos ao que realizamos na seo 5.

Com um procedimento anlogo e continuando a definio de nossa interface, definiremos os mtodos

que retornaro strings no formato JSON:

#region JSON APIs

[OperationContract]
[WebGet(UriTemplate = "json/mensagem/{id}", ResponseFormat =
WebMessageFormat.Json)]
Mensagem JSONGetMensagemByID(string id);

[OperationContract]
[WebGet(UriTemplate = "json/mensagens/{nome}", ResponseFormat =
WebMessageFormat.Json)]
Mensagem[] JSONGetMensagemByNome(string nome);

[OperationContract]
[WebGet(UriTemplate = "json/mensagens", ResponseFormat =
WebMessageFormat.Json)]
Mensagem[] JSONGetMensagens();
 [OperationContract]
[WebInvoke(Method = "DELETE", UriTemplate = "json/mensagem/{id}",
ResponseFormat = WebMessageFormat.Json)]
string JSONDeleteMensagem(string id);

[OperationContract]
[WebInvoke(Method = "POST", UriTemplate = "json/mensagens", ResponseFormat =
WebMessageFormat.Json)]
TextoMensagem JSONPOSTMensagem(/*Mensagem msg*/);

[OperationContract]
[WebInvoke(Method = "PUT", UriTemplate = "json/mensagem/{id}",
ResponseFormat = WebMessageFormat.Json)]
TextoMensagem JSONUpdateMensagem(Mensagem msg, string id);
#endregion
}

#endregion
}

Ao acrescentar o atributo ResponseFormat do WebGet e WebInvoke, podemos defin-lo como

WebMessageFormat.JSON ou WebMessageFormat.XML (padro).

Com isto terminamos de definir nossa interface para os servios disponveis.

7.1 Definindo os Mtodos da Interface

A interface, por definio, apenas molda um prottipo dos mtodos. Agora devemos definir os mtodos
no arquivo Service.svc.cs. Novamente teremos mtodos para XML e mtodos anlogos para JSON.

namespace RESTStarterKit1
{
[ServiceBehavior(IncludeExceptionDetailInFaults = true, InstanceContextMode =
InstanceContextMode.Single, ConcurrencyMode = ConcurrencyMode.Single)]
[AspNetCompatibilityRequirements(RequirementsMode =
AspNetCompatibilityRequirementsMode.Allowed)]
public class Service : IService
{
#region XML Services
public Mensagem XMLGetMensagemByID(string id)
{
methods metodo = new methods();
return metodo.GetMensagemByID(id);
}

public Mensagem[] XMLGetMensagemByNome(string nome)

{
methods metodo = new methods();
return metodo.GetMensagemByNome(nome);
}

public Mensagem[] XMLGetMensagens()

{
methods metodo = new methods();
return metodo.GetMensagens();
}

public string XMLDeleteMensagem(string id)

{
methods metodo = new methods();
return metodo.DeleteMensagem(id, "XML");
}

public TextoMensagem XMLPOSTMensagem()

{
Mensagem msg = new Mensagem();
msg.Nome = HttpContext.Current.Request.Form["nome"];
 msg.Texto = HttpContext.Current.Request.Form["texto"];
msg.Data = DateTime.Now.ToString();
methods metodo = new methods();
return metodo.POSTMensagem(msg, "XML");
}

public TextoMensagem XMLUpdateMensagem(Mensagem msg, string id)

{

texto = HttpContext.Current.Request.Form["texto"];
methods metodo = new methods();
return metodo.UpdateMensagem(texto, id, "XML");

#endregion

A classe methods define as funes de banco de dados. Ela foi criada a fim de reaproveitar o cdigo,
visto que os WebMethods para XML e JSON so exatamente iguais, diferenciando-se apenas pelo
atributo ResponseFormat discutido na seo anterior.

O trecho acima define as funes para XML. A seguir as funes para JSON e ento exibiremos a classe
methods sem entrar em detalhes. Como vero apenas um conjunto de mtodos de conexo a um
banco de dados SQL Server que realizam algumas queries SQL. Foge do intuito deste documento discutir
as bibliotecas e mtodos de conexo do ADO.NET.
Todos os fontes podero ser encontrados no Apndice.

#region JSON Services

public Mensagem JSONGetMensagemByID(string id)
{
methods metodo = new methods();
return metodo.GetMensagemByID(id);
}

public Mensagem[] JSONGetMensagemByNome(string nome)

{
methods metodo = new methods();
return metodo.GetMensagemByNome(nome);
}

public Mensagem[] JSONGetMensagens()

{
methods metodo = new methods();
return metodo.GetMensagens();
}

public string JSONDeleteMensagem(string id)

{
methods metodo = new methods();
return metodo.DeleteMensagem(id, "JSON");
}

public TextoMensagem JSONPOSTMensagem()

{
Mensagem msg = new Mensagem();
msg.Nome = HttpContext.Current.Request.Form["nome"];
msg.Texto = HttpContext.Current.Request.Form["texto"];
msg.Data = DateTime.Now.ToString();
methods metodo = new methods();
return metodo.POSTMensagem(msg, "JSON");
}

public TextoMensagem JSONUpdateMensagem(Mensagem msg, string id)

{
texto = HttpContext.Current.Request.Form["texto"];
methods metodo = new methods();
 return metodo.UpdateMensagem(texto, id, "JSON");
}

#endregion

vlido um comentrio a respeito da classe HttpContext utilizada nos mtodos POST.

Esta classe utilizada para interpretar e realizar requisies HTTP. Em nosso caso, a utilizamos para
receber os dados contidos no Request Body da requisio POST (nome e texto) para montar nosso
objeto do tipo Mensagem e pass-lo para a funo que realiza cadastros no banco de dados.

Seus principais atributos e mtodos so:

HttpContext.Current: possui os atributos HttpContext.Current.Request.QueryString[] e
HttpContext.Current.Request.Form[] os quais recebem os valores de variveis definidas no Request
Body de solicitaes GET e POST respectivamente. De acordo com a especificao do verbo GET, no
devemos enviar dados com este mtodo. Isto funo dos verbos POST e PUT, muito embora seja
possvel este tipo de requisio.

Com isso definimos as operaes a serem realizadas a partir da chamada de cada WebMethod, quando
uma dada requisio feita a uma das URIs definidas na seo anterior, finalizando a criao de nosso
RESTful WebService.

8. Publicando o WebService no IIS (Internet Information Services):

Podemos utilizar a ferramenta Publish do Visual Studio 2008 para publicar os arquivos necessrios para
a execuo dos servios em uma pasta que esteja configurada no IIS para receber chamadas. Certifique-
se de que as configuraes de autenticao e de alias da pasta compartilhada na web estejam corretas.
Seu WebService dever estar acessvel atravs do endereo http://localhost/RESTWS/Service.svc, onde
RESTWS o alias definido no IIS para a pasta que contm os arquivos publicados.

Os ISS 6.0 e 7.0 no aceitam os mtodos PUT e DELETE por padro. necessrio ativ-los.
Para isto, necessrio instalar um novo componente do Windows chamado WebDAV, localizado dentro
do componente IIS/Servio Web em Adicionar ou Remover Componentes do Windows.
Alm disto, necessrio configurar o IIS para que os arquivos .svc aceitem requisies PUT e DELETE.
Na pasta do diretrio virtual criado para seu WebService, v em Propriedades, na aba Diretrio Virtual

Configuraes. Uma lista de extenses de arquivo ser aberta. Encontre a extenso .svc e adicione os
mtodos PUT e DELETE.

9. Consumindo o WebService atravs de uma pgina HTML/JavaScript.

Esta , talvez , a parte mais complicada do processo. Com o Visual Studio e WebServices do tipo SOAP,
bastaria adicionar uma WebReference ao projeto para ter acesso aos WebMethods e utiliz-los como
funes internas ao projeto. Com RESTful WebServices isto no possvel.

Devemos criar um client (no caso, uma Web-Page) capaz de realizar chamadas HTTP a partir de
diferentes mtodos (os 4 definidos pelo nosso projeto: DELETE, GET, POST, PUT).

Se voc familiarizado com o desenvolvimento Web, rapidamente perceber um grande problema:

Forms HTML no so capazes de realizar solicitaes do tipo DELETE e PUT. H uma grande discusso
dentro da comunidade de desenvolvedores a respeito do release do HTML 5, o qual dever trazer estas
funcionalidades. Enquanto isto no possvel, temos aqui um grande problema.

A nova maneira de escrever JavaScript, conhecido como AJAX (Asynchronous Javascript And XML), faz
uso de objetos de conexo HTTP nativos dos principais navegadores para realizar transaes dentro do
protocolo. Desta maneira torna-se possvel especificar as URIs de destino, os verbos HTTP utilizados na
chamada e os parmetros do Request Body.

Com AJAX tambm possvel receber os dados em JSON ou XML (sendo mais comum o XML) e trat-los,
expondo-os, por exemplo, com tags HTML em uma pgina.

9.1 O cdigo AJAX

Primeiramente iremos considerar que tanto o WebService quanto a web-page consumidora esto
hospedados em um mesmo domnio. Discutiremos os motivos desta separao de casos na prxima
seo.

Os fontes completos desta etapa esto disponveis no Apndice. Vamos nos reter a discutir alguns
trechos de cdigo e aspectos importantes do consumo de RESTful WebServices.

Para realizar uma requisio por JavaScript (AJAX), devemos instanciar um objeto do tipo
XmlHttpRequest. Este objeto diferente em alguns navegadores, portanto, devemos detectar qual
navegador estamos trabalhando e instanci-lo de acordo. Para isso, usamos a funo
GetXmlHttpObject();

function GetXmlHttpObject()
{
xmlHttp = null;
try
{
// Firefox, Opera 8.0+, Safari
xmlHttp = new XMLHttpRequest();
}
catch (e)
{
// Internet Explorer
try
{
 xmlHttp = new ActiveXObject("Msxml2.XMLHTTP");
}
catch (e)
{
xmlHttp = new ActiveXObject("Microsoft.XMLHTTP");
}
}
return xmlHttp;
}

function XMLListarBtn_Click ()
{
method = "GET";
url = http://localhost/Service.svc/xml/mensagens";
xmlHttp = GetXmlHttpObject();
if (xmlHttp == null)
{
alert("Seu navegador no suporta AJAX.");
return;
}
xmlHttp.open(method, url, true);
xmlHttp.onreadystatechange = XMLListarMsgs;
xmlHttp.send(null);
}

Ento, adicionamos uma funo ao boto XMLListarBtn em seu evento de onClick. Esta funo utiliza o
objeto XmlHttpRequest devidamente selecionado e realiza a requisio. No caso, do tipo GET.

Cada mudana de estado na requisio (0: No-Iniciada, 1: Aberta, 2: Enviada, 3: Recebendo, 4:

Concluda) gera um evento. Estes eventos so tratados pela funo explicitada no atributo
onreadystatechange:

function XMLListarMsgs ()
{
if (xmlHttp.readyState == 1)
{
//diz que a requisicao est sendo carregada (...)
}
//quando a request estiver concluda e a resposta for 200 OK
if (xmlHttp.readyState == 4 && xmlHttp.status == 200)
{
//mostra pagina (...)
}
//se a request estiver concluida e a pagina nao for encontrada
if (xmlHttp.readyState == 4 && xmlHttp.status == 404)
{
//Not-Found (...)
}
}

O atributo status recebe o valor do estado da requisio, tratados na Introduo (seo 1.2.1).
Para mais detalhes sobre a leitura das respostas s requisies utilizando JavaScript, consulte os fontes
comentados no Apndice.

9.2 Cross-Domain Policy: Um problema para o AJAX

At agora consideramos que client e service esto localizados dentro do mesmo servidor (domnio). Em
nossos projetos, dificilmente encontraremos esta situao.
Normalmente desenvolveremos clients para consumir WebServices de terceiros, localizados em outros
domnios. Da mesma maneira, poderamos desenvolver servios que seriam consumidos por outros
desenvolvedores que no residem sob mesmo servidor que ns.

A Cross-Domain Policy probe o uso de JavaScript para se comunicar diretamente com servidores
remotos. Ou seja, no possvel realizar requisies HTTP utilizando o objeto XmlHttpRequest do AJAX
para outros domnios.

Para realizar tais requisies atravs de uma aplicao Web baseada em AJAX, devemos utilizar um
servidor proxy. Este servidor recebe requisies HTTP e as encaminha para seus destinos finais, atuando
como mediador na comunicao client-server. Uma aplicao deste tipo teria que ser escrita utilizando
alguma linguagem server-sided como C#, Java ou PHP, por exemplo.

Isto nos faz refletir em duas possibilidades:

1. Utilizar Web-Client baseado em AJAX com Proxy Server ver Anexo A;

2. Criar uma Web-Page utilizando linguagem server-sided;

Na primeira opo temos a possibilidade de criar diversos clients diferentes e centralizar as requisies
no servidor proxy, facilitando a manuteno do sistema. Outro ponto importante que a renderizao
das pginas ocorre apenas no lado do client, poupando trabalho do servidor, que fica designado apenas
para remeter as requisies ao WebService.

Desta forma poderamos ter diversos clients independentes e um nico servidor proxy, todos localizados
no mesmo domnio, onde o trabalho do servidor de apenas repassar requisies e respostas.

Para a segunda opo, cada client deveria atuar como servidor, para rodar a aplicao. Esta opo exige,
alm de clientes-servidores, que estas mquinas sejam capazes de renderizar todo o contedo das Web-
Pages consumidoras e, ao mesmo tempo, realizar as requisies HTTP necessrias ao Web-Service. Isto
gera uma grande quantidade de trfego na rede, tornando as aplicaes mais lentas.

Existem bibliotecas Java e C# capazes de interpretar e realizar requisies HTTP de todos os tipos. Alm
disto, o PHP possui uma classe que utiliza mtodos do CURL para realizar estas requisies. CURL um
programa de console freeware escrito em C capaz de realizar quaisquer tipos de requisio HTTP.

Requisio no lado do Servidor

Outra maneira de fugir do problema criado pela Cross-Domain Policy realizar a requisio HTTP no
lado do servidor.

Utilizando C#, isto pode ser feito com as classes HttpWebRequest e HttpWebResponse, da seguinte
maneira:

/*** Cria HTTP Request para serv.baseUrl ***/

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
request.ContentType = "application/x-www-form-urlencoded";
request.Method = method;

HttpWebResponse response = (HttpWebResponse)request.GetResponse();

Stream responseStream = response.GetResponseStream();

StreamReader responseReader = new StreamReader(responseStream);

return responseReader.ReadToEnd();
O parmetro url uma string e define a URI com a qual a requisio deve ser feita. O retorno deste
mtodo uma string, que pode ser um documento XML ou JSON, conforme discutido nas sesses
anteriores.

O verbo http definido no parmetro method em formato de string: GET, POST, PUT ou
DELETE, por exemplo.

10. Aplicao ao projeto X-GOV e ao conceito de Cross-Media

Durante estas nove sees, discutimos a teoria envolvida na arquitetura REST, os conceitos do protocolo
HTTP, como criar uma aplicao RESTful de WebService e como consum-la. Nesta seo, iremos discutir
como esta tecnologia pode ser utilizada no conceito de cross-media, especificamente com relao ao
projeto X-GOV.

No ambiente de cross-media, aplicaes de celular, televiso digital interativa e Web sites convivem
juntas. So meios de comunicao muito diferentes, residindo sob plataformas de desenvolvimento
distintas e com poucas coisas em comum. Uma delas, a principal funo: transmitir informaes.

A interligao destas informaes atravs das diferentes mdias existentes a essncia do cross-media.
Torna-se necessrio, ento, que encontremos no meio de tantas diferenas algumas interssees para
explorar dentro das nossas necessidades.

Uma aplicao independente de plataforma que se comunica atravs de um protocolo padro e

entendido por todas as mdias seria excelente. Esta a deixa para a atuao dos WebServices em mdia
cruzada.

WebServices, tanto SOAP como RESTful, so portveis, multiplataforma e se comunicam atravs de

protocolos padres. Um WebService pode ser acessado tanto por uma aplicao Web (ou Web-Mobile)
como vimos anteriormente, quanto por uma aplicao de Televiso Digital, provendo interoperabilidade
entre as mdias.

O Projeto X-GOV pretende utilizar as diversas mdias, de forma interligada, para desenvolver um
framework baseado em servios de governo, capaz de facilitar o desenvolvimento de aplicaes
governamentais.

Os diversos mdulos do framework devem ser comunicar, acessar bancos de dados, interoperar entre as
diferentes mdias e devolver informaes ao desenvolvedor. Uma boa maneira de resolver todos estes
problemas de comunicao interna por meio de WebServices.

J discutimos anteriormente as vantagens do REST sobre o SOAP (ver seo 2), considerando apenas o
protocolo HTTP. Como esta comunicao interna dos mdulos do framework e, futuramente, das
aplicaes governamentais desenvolvidas a partir dele, exige grande agilidade e compactao dos dados
transferidos, os RESTful WebServices aparecem como soluo melhor que os SOAP.

11. Concluso

Aps este estudo, podemos concluir que o projeto X-GOV pode utilizar os WebServices como meio de
comunicao interna pois:

a) So portveis e multiplataforma;
b) Utilizam protocolos padres, reconhecidos pelas diferentes mdias;
c) Garantem a comunicao cross-mdia;
 d) So aplicaes Web de fcil manuteno, desenvolvimento e uso;
e) Podem realizar tarefas em diversos bancos de dados.

Alm disto, podemos dizer que as aplicaes RESTful so mais eficientes que as aplicaes SOAP para o
projeto pois:

a) No empacotam grandes quantidades de informao;

b) Utilizam mtodos padres de um protocolo padro (HTTP) ao invs de mtodos especficos
para cada aplicao;
c) Podem ser consumidos a partir de simples chamadas HTTP, no sendo necessrio importar
as classes e mtodos do WebService, como feito em SOAP, para a aplicao cliente.
d) Dentro do projeto, podem realizar as mesmas tarefas que as aplicaes SOAP.

Anexo A: Aplicao do Proxy Pattern ao Projeto XGOV

Descrio do padro:

O Proxy Design Pattern faz com que clients de uma determinada aplicao se comuniquem com um
representante desta aplicao, chamado Proxy, ao invs de se comunicarem diretamente com ela.
Desta maneira, mais fcil restringir o acesso aplicao e garantir a consistncia dos dados trafegados.

Contexto:

Um client necessita acessar servios de outro componente, localizado em outra mquina, e uma
conexo direta pode ser possvel tecnicamente, mas no a melhor alternativa.

Problema:

Normalmente no apropriado acessar um componente diretamente, pois se faz necessrio codificar a

conexo diretamente no client, o que permite acesso sem restries ao servio. Isto gera ineficincia e
insegurana ao sistema.
Uma soluo para este problema deve satisfazer ao mximo as seguintes exigncias:

a) O acesso ao componente deve ser em tempo-real, de baixo custo e seguro para ambas as
partes;
b) O acesso deve ser claro e transparente para o cliente. Ele deve saber para onde est sendo
redirecionado e quais etapas do processo esto sendo executadas. O client no deve ter
que alterar o comportamento e sintaxe de suas requisies;

Soluo:

Faa com que o client se comunique com um representante da aplicao original, ao invs de se
comunicar diretamente ela. Este representante deve oferecer uma interface igual ou semelhante
original, porm pode agregar procedimentos antes e aps a requisio, como autenticao, e garantir
apenas a leitura dos dados, no permitindo alteraes ou gravaes diretamente.

Implantao:

1. Identifique todas as tarefas que o servio original prov. Agregue estas tarefas ao Proxy.
2. Se possvel, introduza uma classe abstrata que especifica partes comuns entre a interface do
Proxy e da aplicao original. Procure fazer as interfaces o mais idnticas possvel, para que o
client continue pensando que est trabalhando diretamente na aplicao final.
 3. Programe as funes extras do Proxy, como autenticao e validao de dados.
4. Remova dos clients e da aplicao original todas as funes que agora residem no client.
5. Faa a comunicao entre o Proxy e o original. Esta comunicao pode ser feita atravs de um
socket, ponteiro, referncia, porta, endereo, entre outros.
6. Remova todas as ligaes diretas entre os clients e a aplicao final, substituindo-as por
conexes anlogas entre o client e o Proxy e entre a aplicao e o Proxy.

Conseqncias:

O uso de proxies torna a aplicao menos eficiente devido aos redirecionamentos. Normalmente este
problema compensado pela agilidade adquirida nos processos agregados ao Proxy, que antes residiam
no client ou na aplicao original.

Outro problema o uso descontrolado de armazenamento e carregamento de informaes em run-

time. Isto torna a aplicao lenta e passvel de problemas, conforme a aplicao cresce ou exige uma
transferncia de dados constante e volumosa.

Os benefcios do uso de proxies so, essencialmente, a reduo de custo do sistema e a eficincia

gerada pelas funes agregadas ao Proxy. Alm disto, um Proxy retira dos clients informaes perigosas
de localizao do servidor dos componentes, na medida em que se torna mais parecido com a aplicao
original.

Uso do Proxy Pattern no projeto X-GOV

O conjunto de componentes de mdulos que o framework X-GOV disponibilizar depende de um grande

fluxo de informao interna ao sistema, alm de ter de gerir as informaes que so requisitadas pelas
diferentes mdias quando usadas pelos cidados.

Toda esta comunicao dever ser autenticada, para evitar fraudes ao sistema e garantir a segurana
das informaes contidas. Alm disto, muitos usurios e diversas aplicaes do framework faro uso de
um mesmo conjunto de ferramentas e dados do sistema, o que torna a utilizao de servios web
bastante plausvel.

Todos estes servios faro a comunicao framework base de dados, framework framework e
framework usurio. Este contexto se encaixa perfeitamente ao contexto apresentado pelo Proxy
Pattern.

Como necessrio esconder dos clients a localizao do sistema e diversos mtodos internos, autenticar
usurios, gerir os dados fornecidos e tratar dos dados apresentados, uma comunicao direta client
servios se torna arriscada e inapropriada. Em muitos casos, a tecnologia empregada como no caso do
REST e AJAX impede o acesso direto.

Para resolver este problema, podemos adotar um ou mais servidores Proxy. Estes servidores fariam a
mediao entre os clients, que podem ser dispositivos do usurio, webservices ou mdulos do
framework X-GOV, e os servidores de dados ou servios. Desta forma, centralizamos as chamadas em
determinados servidores, que sero responsveis por garantir a autenticao dos usurios e fazer uma
conexo segura com os servios internos do sistema.
 Referncias Bibliogrficas

Sites:
Wikipedia: http://en.wikipedia.org/wiki/Main_Page realizando buscas por HTTP, REST e Status-Code.
W3C: http://www.w3schools.com/Ajax/Default.Asp para tutoriais e exemplos AJAX.
Vdeos:
Getting Started with REST Starter Kit, por Aaron Skonnard. Disponveis no site da MSDN;
WCF: Developing RESTful Services, realizado no PDC 2008, por Steve Maine e Rob Bagby;
Artigos:
A Guide to Designing and Building RESTful Web Services with WCF 3.5, por Aaron Skonnard. Disponvel
em: http://msdn.microsoft.com/en-us/library/dd203052.aspx.
Architectural Styles and the Design of Network-based Software Architectures, Roy Fielding , captulo 5
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
Livros:
PATTERN-ORIENTED SOFTWARE ARCHITECTURE Vol1. Pg: 263 a 275.