Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Sobre o autor
Emlio Dias
Instrutor da AlgaWorks, formado em Cincia da
Computao, Especialista em Segurana da
Informao e detentor das certificaes SCJP e
LPIC-1. Palestrante de fruns internacionais de
Software Livre e congressos de Engenharia de
Software. Atua tambm como Professor nos cursos
de Cincia da Computao e Sistemas de Informao da Unitri em Uberlndia.
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?
Sumrio
1 Introduo
2 REST
2.1
Cliente-servidor .......................................................................................... 13
2.2
Stateless ....................................................................................................... 14
2.3
Cache ............................................................................................................ 15
2.4
2.5
2.6
3 REST ou RESTful?
3.1
3.2
Recursos ...................................................................................................... 19
3.3
Mtodos ....................................................................................................... 24
5.2
5.3
5.4
6 Concluso
Captulo 1
Introduo
Voc certamente j deve ter ouvido falar em Web Services RESTful, no
mesmo?
Muito tem se falado a respeito sobre formas de integrao de sistemas comerciais,
aplicativos mveis e tantos outros. Mas qual a melhor forma de realizar esta
integrao?
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.
Primeiramente, muitas empresas adquirem software de vrios fornecedores e
precisam de alguma forma fazer todos eles se comunicarem. Neste sentido, os
Web Services ajudam como uma ponte de ligao entre os mesmos. O segundo
aspecto at um pouco mais interessante, e pra falar sobre ele, vou te contar uma
pequena histria.
A forma na qual interagimos com meios computacionais vem evoluindo
consideravelmente com o passar do tempo. Nos ltimos anos, temos
acompanhado o surgimento de Smart TVs, Smartphones, Tablets, Internet das
Coisas, dentre tantos outros. O aparecimento de tais dispositivos e tecnologias,
impactam diretamente o nosso dia a dia.
www.algaworks.com
10
www.algaworks.com
11
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.
Baseado nisso, nesse livreto ns vamos discutir como o modelo arquitetural
REST e o Java podem nos ajudar na implementao de solues que atendam
essa quantidade de requisitos. Vamos falar tambm sobre a origem do REST,
apresentar e tirar algumas dvidas e confuses que sempre aparecem quando
esse assunto discutido.
www.algaworks.com
12
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.
O intuito geral era a formalizao de um conjunto de melhores prticas
denominadas constraints. Essas constraints tinham como objetivo determinar a
forma na qual padres como HTTP e URI deveriam ser modelados, aproveitando
de fato todos os recursos oferecidos pelos mesmos.
Vamos conhecer um pouco melhor essas contraints?
2.1. Cliente-servidor
A principal caracterstica dessa constraint separar as responsabilidades de
diferentes partes de um sistema. Essa diviso pode se dar de diversas formas,
iniciando por exemplo com uma separao entre mecanismos de armazenamento
de dados e o back-end da aplicao.
Outra diviso muito comum se d entre a interface do usurio e back-end. Isso
nos permite a evoluo e escalabilidade destas responsabilidades de forma
independente. Atualmente vrias ferramentas seguem este modelo, frameworks
como AngularJS e APIs RESTful permitem o isolamento de forma elegante para
cada uma dessas funcionalidades.
1. http://www.ics.uci.edu/~fielding/
www.algaworks.com
13
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.
Um dos principais inconvenientes no uso de cookies que sua utilizao diminui
de forma drstica a forma na qual podemos escalar nossas aplicaes. A figura
abaixo ilustra um pouco melhor essa situao.
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
14
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.
O protocolo HTTP permite o funcionamento adequado dessa constraint a partir
da adio dos headers expires (verso 1.0 do HTTP) e/ou cache-control
(verso 1.1 do HTTP).
www.algaworks.com
15
requisio. Esse modelo permite que o servidor execute apenas tarefas que
realmente so necessrias.
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
16
www.algaworks.com
17
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.
Quando estamos discutindo sobre o modelo e sobre as caractersticas que ns
vimos anteriormente, voc deve utilizar o termo REST, j no momento em que
voc estiver falando de uma implementao que usa essas mesmas
caractersticas, voc deve usar RESTful.
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
18
3.2. Recursos
Um recurso utilizado para identificar de forma nica um objeto abstrato ou
fsico. A RFC 3986 especifica detalhadamente todas as caractersticas que uma
URI deve seguir.
Basicamente, temos a modelagem de um recurso sob um substantivo, ao invs de
verbos, como usualmente utilizado em APIs. Exemplos:
/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 {
@RequestMapping(value = "/{id}", method = RequestMethod.GET,
produces = "application/json")
public ClienteRepresentation buscar(@PathVariable("id") Integer id) {
System.out.println("Retornando cliente...");
return new ClienteRepresentation("Joo da Silva");
www.algaworks.com
19
}
}
@RestController
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.
Quando um recurso solicitado por um cliente (ex: browser), o servidor executa
uma srie de atividades e retorna uma mensagem ao solicitante. Essa mensagem
de fato uma representao de um determinado recurso. A mesma no
necessariamente precisa estar ligada a alguma parte concreta de um sistema,
como por exemplo, uma tabela de banco de dados.
www.algaworks.com
20
Representaes
As representaes podem ser modeladas em vrios formatos, como XML, JSON,
HTML e etc. Voc deve apenas levar em considerao que esse formato deve
suportar a utilizao de hypermedia (posteriormente ns vamos discutir os seus
conceitos).
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.
Isso pode ser feito devido a capacidade de mltiplas representaes (mais
conhecido como negociao de contedo) que o HTTP possui. Para que isso
seja possvel, voc pode usar o header Accept para especificar qual o tipo de
representao mais adequada. A figura abaixo deixa isso um pouco mais claro.
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
21
XML
O XML (eXtended Markup Language) uma linguagem de marcao
recomendada pelo W3C (World Web Consortium) e tem como objetivo a
descrio de qualquer tipo de dados.
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>
JSON
O JSON (JavaScript Object Notation) surgiu como uma alternativa para
representao de dados de uma forma mais simples e leve.
www.algaworks.com
22
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"
}
}
www.algaworks.com
23
3.3. Mtodos
A RFC 72313 especifica um conjunto de 8 mtodos os quais podemos utilizar para
a criao de uma API RESTful. Esse conjunto de mtodos possui a semntica de
operaes possveis de serem efetuadas sob um determinado recurso.
Dentre esses 8 mtodos, abaixo segue um detalhamento dos 4 mais conhecidos.
GET
O mtodo GET utilizado quando existe a necessidade de se obter um recurso.
Ele considerado idempotente, ou seja, independente da quantidade de vezes
que executado sob um recurso, o resultado sempre ser o mesmo. Exemplo:
GET /cliente/1 HTTP/1.1
POST
Utilizado para a criao de um recurso a partir do uso de uma representao.
Exemplo:
POST /cliente HTTP/1.1
<Cliente>
<Nome>Joo da Silva</Nome>
...
</Cliente>
PUT
O mtodo PUT utilizado como forma de atualizar um determinado recurso. Em
alguns cenrios muitos especficos, ele tambm pode ser utilizado como forma
de criao, por exemplo quando o cliente tem a liberdade de decidir a URI a ser
utilizada.
3. https://www.ietf.org/rfc/rfc3986.txt
www.algaworks.com
24
DELETE
O delete tem como finalidade a remoo de um determinado recurso. Exemplo:
DELETE /cliente/1 HTTP/1.1
1xx - Informaes
2xx - Sucesso
3xx - Redirecionamento
4xx - Erro no cliente
5xx - Erro no servidor
www.algaworks.com
25
Para cada um dos tipos acima, existem cdigos especficos que podem ser
aplicados em cada uma das situaes encontradas na manipulao de recursos.
O Spring nos fornece uma srie de medidas para trabalharmos de forma
adequada o cdigo de retorno. Uma dessas formas a criao de uma
RuntimeException, informando que tipo de cdigo ela representa atravs de uma
anotao. Veja um exemplo:
@ResponseStatus(value = HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
}
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
26
www.algaworks.com
27
Captulo 4
www.algaworks.com
28
29
5. http://martinfowler.com/articles/richardsonMaturityModel.html
www.algaworks.com
30
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.
Entusiastas conhecidos como RESTfarians, consideram inapropriado a nomeao
de uma API RESTful se ela realmente no segue todas as constraints definadas
por Fielding.
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.
O modelo proposto por Leonard Richardson7 possui basicamente 4 nveis e tenta
mapear as caractersticas de APIs que podem ser encontradas espalhadas hoje em
sistemas de todo o mundo.
Os nveis 0, 1 e 2 talvez sejam mais familiares pra voc, e de fato so mais
fceis de implementar, porm, deve ficar claro pra voc que os mesmos no so
considerados RESTful. Na figura abaixo podemos ver quais so esses nveis:
6. http://roy.gbiv.com/untangled/2008/restapismustbehypertextdriven
7. http://www.crummy.com/self/
www.algaworks.com
31
www.algaworks.com
32
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)
Verbo HTTP
URI
Ao
GET
/buscarCliente/1
Visualizar
POST
/salvarCliente
Criar
POST
/alterarCliente/1
Alterar
GET/POST
/deletarCliente/1
Remover
REST
Verbo HTTP
URI
Ao
GET
/cliente/1
Visualizar
POST
/cliente
Criar
PUT
/cliente/1
Alterar
DELETE
/cliente/1
Remover
www.algaworks.com
33
<status>CLIENTE NO ENCONTRADO</status>
<codigo>404</codigo>
<buscarCliente>
www.algaworks.com
34
www.algaworks.com
35
www.algaworks.com
36
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).
A imagem pode ser traduzida em um cdigo HTML (Hypermedia Text Markup
Language), para que fique ainda mais claro. Por exemplo, veja como seria o
contedo de index.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
37
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.
Comeamos ento a entender um pouco melhor o significado de HATEOAS.
Como o prprio nome sugere, a representao hypermedia trabalha como um
motor de estado, permitindo que clientes naveguem nos mesmos. Cada estado
um documento (uma pgina HTML) e possui referncias para futuros estados (a
partir de links).
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?
Se analisarmos a forma na qual sistemas Web podem ser construdos ou
remodelados, ns podemos perceber que isso se d sem a necessidade de
atualizao nos clientes (browsers). O contrato inicialmente conhecido, a
linguagem de hypermedia HTML, em conjunto com o protocolo HTTP, abstrai
qualquer acoplamento direto entre o contedo e o que deve ser interpretado pelo
navegador, ou seja, todos os dias so adicionadas, removidas e alteradas centenas
de pginas Web sem que isso tenha impacto direto em cada um dos elementos
envolvidos, como o browser, proxies, gateways, balanceadores de carga e etc.
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
38
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:
GET /cliente/1 HTTP/1.1
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
39
www.algaworks.com
40
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.
No se preocupe se algumas ideias ainda no ficaram muito claras. Realmente,
alguns conceitos so difceis de assimilar inicialmente, porm, fao um
compromisso com voc que ns da AlgaWorks iremos continuar abordando
e publicando bastante contedo sobre esse tema, para que voc consiga
implementar isso da melhor forma possvel no seu trabalho.
De forma resumida, voc aprendeu aqui:
Como o mundo vem mudando e o impacto disso no nosso trabalho
Como a Web pode nos ajudar a construir sistemas cada vez melhores
Caractersticas de aplicaes Web
Simples
Extensvel
Escalvel
Etc
Diferenas entre REST e RESTful
www.algaworks.com
41
www.algaworks.com
42