Escolar Documentos
Profissional Documentos
Cultura Documentos
Algaworks Livreto Desmistificando Rest Com Java v1.1 PDF
Algaworks Livreto Desmistificando Rest Com Java v1.1 PDF
1 Edio, 11/02/2016
LinkedIn: https://www.linkedin.com/in/emiliodias
Antes de comear...
Antes que voc comece a ler esse livro, eu gostaria de combinar algumas coisas
com voc, para que tenha um excelente aproveitamento do contedo. Vamos l?
http://alga.works/comunidadejava/
Ajude a divulgar esse livreto para seus amigos que tambm se interessam por
programao Java. Compartilhe no Facebook e Twitter!
Sumrio
1 Introduo
2 REST
2.1 Cliente-servidor .......................................................................................... 14
3 REST ou RESTful?
3.1 Sendo RESTful com HTTP ........................................................................ 19
Introduo
Voc certamente j deve ter ouvido falar em Web Services RESTful, no
mesmo?
Nesse livreto, vamos apresentar vrios conceitos e tirar uma srie de dvidas
sobre como podemos implementar um Web Service RESTful e como o Java pode
te ajudar nessa caminhada.
Voc j se perguntou por que precisamos de Web Services? Essa uma questo
que podemos avaliar sob vrios pontos de vista, mas eu quero te apresentar dois.
www.algaworks.com 11
O mercado de tecnologia passa constantemente por desafios, para de alguma
forma, atender as necessidades de todos os consumidores, e nem sempre
simples modelar uma soluo adequada para tantos cenrios complexos.
Atualmente difcil imaginarmos um mercado sem vendas pela Web e tambm
a execuo de atividades corriqueiras a partir de um smartphone.
Dizendo isso, fica mais fcil entender que a escolha de uso por uma tecnologia
de Web Services no est associada apenas a um fator tcnico, e sim tambm
ao fato que precisamos desenvolver sistemas de forma que o usurio tenha uma
experincia de uso cada vez melhor.
www.algaworks.com 12
caractersticas que nos permitem criar APIs que suportam tudo aquilo que eu
disse anteriormente. Apenas para citar algumas, vejamos:
Simples
Extensvel
Escalvel
Incremental
Global
E muito mais
Perceba que possumos uma grande plataforma em mos. Exato, podemos passar
a enxergar a Web no apenas como um lugar onde um conjunto enorme de
informaes so encontradas ou pginas Web so disponibilizadas, podemos
comear a trat-la como uma plataforma e usar dos seus benefcios para criar
aplicaes cada vez melhores.
www.algaworks.com 13
Captulo 2
REST
Apesar de aparentemente ser uma proposta nova, REST surgiu no incio dos anos
2000, a partir da tese de Ph.D de um cientista chamado Roy Fielding1.
2.1. Cliente-servidor
1. http://www.ics.uci.edu/~fielding/
www.algaworks.com 14
2.2. Stateless
Essa caracterstica prope que cada requisio ao servidor no deve ter ligao
com requisies anteriores ou futuras, ou seja, cada requisio deve conter todas
as informaes necessrias para que ela seja tratada com sucesso pelo servidor.
O protocolo HTTP segue esse modelo, porm, muito comum o uso de cookies
para armazenamento de sesses do lado do servidor. Essa abordagem deve ser
usada com cautela, visto os inconvenientes que a mesma carrega.
Perceba que o cliente precisa sempre ser redirecionado para o mesmo servidor,
limitando assim questes de alta disponibilidade, escalabilidade e etc. Existem
vrias maneiras de tratar essa questo, por exemplo, podemos usar o modelo
Sticky Session2 ou em um cenrio melhor, devemos sempre que possvel,
transferir a responsabilidade de armazenamento de informaes para os clientes.
2. http://httpd.apache.org/docs/2.2/mod/mod_proxy_balancer.html
www.algaworks.com 15
Segundo Fielding, utilizando um modelo de comunicao stateless, sua API passa
a ter caractersticas como visibilidade, confiabilidade e escalabilidade.
2.3. Cache
Para uma melhor performance, um sistema REST deve permitir que suas
respostas sejam passveis de cache. Cada resposta deve de alguma maneira
informar para clientes ou elementos intermedirios (proxies, gateways e/ou
balanceadores de carga) qual a poltica de cache mais adequada.
www.algaworks.com 16
requisio. Esse modelo permite que o servidor execute apenas tarefas que
realmente so necessrias.
Como temos discutido at agora, podemos ver que REST possui uma srie de
caractersticas, e certamente a interface uniforme uma das mais importantes.
Bastante esforo deve ser feito para que o sistema possua uma interface
modelada seguindo alguns padres importantes. Quando se fala sobre uma
interface, os elementos abaixo devem ser considerados:
Recursos
Mensagens autodescritivas
Hypermedia
Para ficar um pouco mais claro o que de fato vem a ser essa interface, podemos
pensar por exemplo como podemos manipular vendas em um e-commerce. Uma
loja virtual possui diversas entidades, como por exemplo produto, cliente,
pedido e etc. Devemos pensar em criar uma interface que permita a manipulao
desses conceitos. Abaixo um exemplo:
Veja que a figura modela o recurso cliente e uma srie de operaes que podem
ser executadas sob o mesmo. Futuramente vamos discutir como implementar
essa interface e voc ir perceber que cada uma das operaes reflete sob um
mtodo do protocolo HTTP.
www.algaworks.com 17
2.5. Sistema em camadas
Perceba que nos tpicos que discutimos sobre stateless e cache, foi utilizado um
elemento que demos o nome de balanceador. Esse balanceador um dos
elementos que podemos usar e que permite adicionarmos mais servidores para
uma aplicao, sem que o cliente note sua presena.
Voc certamente j deve ter estudado uma srie de artigos e livros sobre boas
prticas de desenvolvimento de software e orientao a objetos. A maioria desses
artigos e livros falam sobre a questo de extensibilidade, que a capacidade que
um software possui de evoluir sem a necessidade de quebra do mesmo.
Cdigo sob demanda permite algo semelhante, ele possibilita adaptar o cliente de
acordo com novos requisitos e funcionalidades. Exemplos disso so o JavaScript
e Applets.
www.algaworks.com 18
Captulo 3
REST ou RESTful?
Voc j deve ter se perguntado sobre a diferena dos termos REST e RESTful,
no ? No se preocupe, uma confuso muito comum o uso intercambivel
desses termos. Mas de fato, uma API ou aplicao deve receber o nome REST ou
RESTful?
De forma bem direta, o correto voc dizer API RESTful. Alm disso,
importante voc entender o porqu dessa nomenclatura e qual o momento certo
de usar cada uma.
Apesar de no ser algo to relevante, achei interessante lhe dizer isso para que
voc sempre utilize as nomenclaturas corretas. Isso tambm nos ajuda a deixar
claro que REST nada mais que um conjunto de boas prticas.
www.algaworks.com 19
Vamos discutir agora a forma mais utilizada de implementao de REST: o
protocolo HTTP. Vamos falar tambm sobre os principais conceitos envolvidos
na criao de uma API RESTful. O objetivo no listar todas as funcionalidades
possveis, mas iremos navegar pelas caractersticas principais que voc deve
conhecer para implementar um Web Service RESTful.
3.2. Recursos
/cliente/1
/produto/1
/cliente/1/notificacao
Uma URI deve ser visualizada como um recurso, e no como uma ao a ser
executada sob um servidor. Alguns autores e literaturas defendem a utilizao de
verbos em casos especficos, porm, isso no totalmente aceitvel e voc deve
usar com cautela.
Para que fique mais claro pra voc, vamos dar uma olhada em como isso pode ser
construdo usando o Spring. No vou entrar em muitos detalhes do framework,
minha ideia aqui lhe mostrar o quo simples pode ser uma implementao
inicial.
@RestController
@RequestMapping("/cliente")
public class ClienteResource {
www.algaworks.com 20
}
{
"nome": "Joao da Silva"
}
Perceba que uma simples informao em formato JSON (falaremos sobre JSON
a seguir), mas que j podemos comear a evoluir.
Voc deve ter reparado que usei a palavra representao para me referir a
mensagem de retorno do Web Service. importante voc sempre usar essa
nomenclatura para que fique claro o que voc deseja informar.
www.algaworks.com 21
Representaes
Para ficar um pouco mais claro, imagine por exemplo o recurso /cliente/1,
que discutimos anteriormente. Naquele caso, ns usamos uma representao em
formato JSON, mas ns poderamos tambm querer represent-lo a partir de uma
imagem.
Note que para cada tipo de formato requisitado, o servidor retornou uma
resposta com uma representao adequada.
Agora vamos fazer uma rpida reviso sobre os formatos JSON e XML, que so
os mais utilizados em APIs na atualidade, para caso voc ainda tenha alguma
dvida sobre eles.
www.algaworks.com 22
XML
Ele utilizado como uma forma padro para troca de informaes entre sistemas
ou at mesmo para armazenamento dos mesmos. Abaixo, podemos ver a
estrutura de um documento XML:
<cliente>
<id>10</id>
<nome>Alan Turing</nome>
<nascimento>23/06/1912</nascimento>
<profissao>Matemtico</profissao>
<endereco>
<cidade>Manchester</cidade>
<pais>Inglaterra</pais>
</endereco>
</cliente>
Baseado nisso, podemos utilizar uma soluo mais enxuta, que iremos discutir a
seguir.
JSON
www.algaworks.com 23
Como voc deve ter percebido, JSON est relacionado linguagem JavaScript,
porm, esse formato de dados pode ser utilizado independente da tecnologia que
voc estiver usando. Veja abaixo um exemplo:
{
"id": 10,
"nome": "Alan Turing",
"nascimento": "23/06/1912",
"profissao": "Matemtico",
"endereco": {
"cidade": "Manchester",
"pais": "Inglaterra"
}
}
Leitura simplificada
Analisador mais simples
Suporte de vrios frameworks atuais (principalmente frameworks
JavaScript)
Tamanho reduzido
Por esses e mais vrios outros fatores, o JSON est cada dia mais disseminado na
comunidade.
De forma resumida, perceba que tanto XML quanto JSON, so formatos que
utilizamos para descrever os dados de nossas aplicaes, e que para cada cenrio
devemos verificar qual se encaixa de forma mais adequada. Principalmente pela
sua simplicidade, o JSON vem ganhando mais seguidores.
www.algaworks.com 24
3.3. Mtodos
GET
POST
PUT
3. https://www.ietf.org/rfc/rfc3986.txt
www.algaworks.com 25
DELETE
Para tornar nossa vida um pouco mais simples, o Spring nos ajuda a desenvolver
essas operaes de forma bem tranquila. Vamos dar uma olhada em como isso
pode ser feito.
Desta forma, toda requisio DELETE HTTP que chegar ao servidor ser
encaminhada ao mtodo excluir.
1xx - Informaes
2xx - Sucesso
3xx - Redirecionamento
4xx - Erro no cliente
5xx - Erro no servidor
www.algaworks.com 26
Para cada um dos tipos acima, existem cdigos especficos que podem ser
aplicados em cada uma das situaes encontradas na manipulao de recursos.
@ResponseStatus(value = HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
}
Voc deve estar perguntando a forma na qual devemos lanar essa exceo.
Ento veja um cdigo de exemplo abaixo:
Perceba que a utilizao da exceo funciona da mesma forma que voc j deve
estar habituado a trabalhar.
Apesar de termos utilizado cdigos bem simples, meu intuito aqui lhe
demonstrar que necessria pouca codificao para o desenvolvimento de um
Web Service RESTful. Obviamente, existem inmeras outras possibilidades, mas
voc j deve estar comeando a visualizar o caminho a ser seguido.
Alm dos itens que discutimos at aqui, o HTTP possui suporte a diversos
outros recursos que podem ser muito teis na modelagem de uma API RESTful.
Dentre eles, pode-se citar web linking, negociao de contedo, queries, caching,
www.algaworks.com 27
requisies condicionais e segurana. Com o Spring podemos trabalhar com
todas essas caractersticas.
www.algaworks.com 28
Captulo 4
Talvez voc j tenha desenvolvido ou pelo menos tenha ouvido falar em Web
Services SOAP, e sempre h uma discusso sobre qual a melhor abordagem
(REST ou SOAP).
Por que ento existe essa confuso? Muitos sistemas, na verdade, so modelados
em um formato conhecido como POX (Plain Old XML), que basicamente consiste
na passagem de uma mensagem XML utilizando como transporte o protocolo
HTTP.
www.algaworks.com 29
A confuso ainda maior quando o formato da mensagem utiliza JSON. Nesse
caso, temos um mesmo modelo arquitetural (RPC), usando apenas um formato
de mensagem diferente.
Talvez agora voc esteja com dvidas sobre o que esse tal de RPC.
Imagine por exemplo, uma classe Java e seus diversos mtodos, o RPC um
modelo que visa a disponibilizao desses mtodos para execuo de forma
remota (a partir de outro computador)4.
O SOAP baseado nesse formato, ou seja, ele expe uma srie de mtodos Java
(ou outra linguagem), para que eles possam ser executados sob mensagens em
formato XML.
Diante disso, necessrio ficar claro que a escolha entre REST e SOAP vai
muito alm do formato de mensagens que so trocadas entre sistemas. Essas
abordagens devem ser elevadas a um patamar de modelo arquitetural.
necessrio a utilizao de um modelo com as caractersticas providas por REST?
O modelo RPC, implementado pelo SOAP e enriquecido com uma srie de outras
especificaes conhecidas como WS-*, o mais adequado?
Lembre-se apenas que no existe um modelo One size fits all, ou seja, REST ou
SOAP no a bala de prata para a resoluo de todos os problemas.
Muito dessa confuso se d pelo fato de APIs ditas como RESTful receberem
esse ttulo sem nenhuma credibilidade, ou seja, elas tem muito poucas
caractersticas necessrias para serem realmente RESTful.
www.algaworks.com 30
Com o intuito de desmistificar um pouco dessa confuso, vamos discutir sobre
o Modelo de Maturidade Richardson5 no prximo captulo, que tem como
propsito mapear em que nvel uma API se apresenta e se de fato ela realmente
pode ser considerada RESTful.
5. http://martinfowler.com/articles/richardsonMaturityModel.html
www.algaworks.com 31
Captulo 5
Modelo de maturidade
Richardson
Apesar de Roy Fielding deixar bastante claro que para uma API ser considerada
RESTful ela precisa obrigatoriamente seguir todas as constraints definidas em seu
trabalho6, e o mais importante, fazer uso de hypermedia, na prtica, muitas vezes
precisamos de uma abordagem um pouco mais simples.
Apesar de tudo isso, o mercado tem uma outra realidade, e com o intuito de
mapear e clarear os pensamentos, um modelo de maturidade foi criado.
6. http://roy.gbiv.com/untangled/2008/restapismustbehypertextdriven
7. http://www.crummy.com/self/
www.algaworks.com 32
Modelo de maturidade Richardson
Fonte: http://martinfowler.com/articles/richardsonMaturityModel.html
Voc certamente j deve ter desenvolvido ou visto em algum lugar uma API
que segue esse modelo de design. Apesar de ser o nvel mais distante do que
de fato REST prope, muitas APIs ditas como RESTful se encontram neste nvel
de maturidade. Neste cenrio, o protocolo HTTP utilizado apenas como
mecanismo de transporte e o que se v um modelo arquitetural fortemente
baseado em RPC.
Neste nvel, as mensagens podem ser serializadas em formatos como XML, JSON
ou outros. importante lembrar, como dito anteriormente, que no o formato
da mensagem que define ou no um sistema REST. Veja abaixo um exemplo de
API em nvel 0:
www.algaworks.com 33
URIs devem ser modeladas com o uso de substantivos. Veja abaixo uma tabela
com URIs mapeadas no formato RPC e no formato REST.
RPC (POX)
REST
HTTP/1.1 200 OK
<buscarCliente>
www.algaworks.com 34
<status>CLIENTE NO ENCONTRADO</status>
<codigo>404</codigo>
<buscarCliente>
www.algaworks.com 35
5.3. Nvel 2 - Verbos HTTP
Criando um cliente:
www.algaworks.com 36
GET /cliente/1 HTTP/1.1
HTTP/1.1 200 OK
<Cliente>
<Id>1</Id>
<Nome>Joo da Silva</Nome>
...
</Cliente>
Caso seja necessrio a remoo desse recurso, voc pode utilizar o mtodo
DELETE, como mostrado abaixo:
Este nvel certamente a maior dvida quando se fala sobre REST. Existe uma
srie de perguntas sobre o que realmente significa HATEOAS (Hypermedia as the
Engine of Application State) e qual o papel disso em uma API.
Em seu blog pessoal, Fielding deixa muito claro que APIs que no utilizam
HATEOAS no podem ser consideradas RESTful, mesmo assim, voc vai
encontrar muitos contedos sobre REST que nem ao menos cita essa
caracterstica.
A figura abaixo nos ajuda a entender um pouco melhor o que isso significa.
www.algaworks.com 37
Perceba que a figura nos mostra uma srie de estados e que a ligao entre os
mesmos se d a partir de uma URI. O termo estado utilizado para denominar
cada representao que o servidor responde quando um recurso solicitado (ex:
uma pgina HTML).
<html>
<body>
<a href="produtos.html">Produtos</a>
<a href="clientes.html">Clientes</a>
<a href="contato.html">Contato</a>
<a href="carrinho.html">Carrinho</a>
</body>
</html>
No cdigo HTML acima, podemos notar a presena da tag <a>, que diz ao cliente
HTML (normalmente um browser) que ele deve executar um GET sob cada um
dos recursos contidos no atributo href.
www.algaworks.com 38
Como eu posso garantir que sempre que uma tag <a> aparecer, o browser ir
fazer um GET? Isso se d pelo fato da especificao do HTML nos dizer que toda
vez que uma tag <a> estiver presente, uma mensagem GET deve ser enviada
URI descrita no atributo href, ou seja, existe um pr-contrato entre browsers e
servidores.
Dito tudo isso, agora conseguimos entender de forma mais clara a prpria origem
do nome Web (no portugus, teia). O mesmo se d pelo fato de links
interligarem um conjunto de recursos, formando assim uma enorme teia.
Resumindo, podemos ver que o HTML uma linguagem que permite que
aplicaes sejam construdas seguindo o modelo HATEOAS. Porm, como deve
ser feita a modelagem de uma API para que ela siga o mesmo formato? E qual o
benefcio dessa abordagem?
Considerando a mesma abordagem para APIs, isso significa que voc pode
criar APIs totalmente desacopladas e que podem evoluir sem a necessidade de
atualizaes do lado dos clientes.
Voc j se imaginou criando sistemas que podem evoluir sem que haja um
impacto dentro de vrios sistemas da organizao? J pensou em criar sistemas
que possam atender milhares de usurios, assim como servios que funcionam
hoje na Internet?
www.algaworks.com 39
Criar APIs RESTful significa criar APIs que seguem cada uma das constraints
descritas nesse livro e suportar HATEOAS. Com isso, voc ter a possibilidade
de alcanar os benefcios que te mostrei, criando APIs realmente escalveis,
extensveis e com todas as outras caractersticas que a Web possui.
Criar APIs que seguem essa abordagem e programar clientes que usem deste
benefcio um enorme desafio, visto que o modelo mental utilizado em
aplicaes atuais so fortemente baseadas no modelo RPC.
Neste livro, no vou entrar em detalhes sobre como proceder com a criao de
clientes de APIs RESTful, mas j deixe em mente que precisamos trabalhar uma
forma de criar clientes que usufruam de todos esses benefcios.
Para exemplificar, veja abaixo uma pequena representao de uma API que
utiliza hypermedia:
HTTP/1.1 200 OK
<Cliente>
<Id>1</Id>
<Nome>Joo da Silva</Nome>
<link rel="deletar" href="/cliente/1" />
<link rel="notificar" href="/cliente/1/notificacao" />
</Cliente>
www.algaworks.com 40
A modelagem de uma API baseada em hypermedia passa pelo processo de
definio sobre qual a melhor linguagem utilizada. Cada API possui
caractersticas isoladas e precisa ser pensada de forma particular, porm, alguns
padres podem ser utilizados, como o prprio HTML, ATOM PUB ou at mesmo
a criao de uma linguagem prpria.
Acompanhe a AlgaWorks por e-mail e redes sociais, porque ainda vamos falar
muito sobre esse assunto.
www.algaworks.com 41
Captulo 6
Concluso
Chegamos no final do livreto e estou muito feliz por voc ter me acompanhado!
Talvez voc tenha se surpreendido com uma srie de coisas que voc aprendeu
por aqui. Realmente, existem vrios materiais na Web que no condizem ou
simplificam muito toda a histria por trs do REST. Por isso, importante voc
selecionar os materiais confiveis.
Minha ideia foi realmente abrir um pouco das cortinas e lhe mostrar o que
acontece de fato por trs dos palcos deste vasto mundo de APIs RESTful.
www.algaworks.com 42
6.1. Prximos passos
Agora que voc j sabe o que REST, eu recomendo que voc aprenda na prtica
como implementar Web Services RESTful com Spring (Java).
www.algaworks.com 43