33

Estou estudando REST e desenvolvimento de Web API's e ouvi falar sobre HATEOAS (Hypertext as the engine of application state). Eu entendi a ideia: ao responder uma requisição, além do que normalmente retornamos, a ideia é também retornar dados sobre o que pode ser feito em seguida. Um exemplo que vi na internet foi esse:

GET /account/12345 HTTP/1.1 HTTP/1.1 200 OK 
<?xml version="1.0"?> 
<account> 
    <account_number>12345</account_number> 
    <balance currency="usd">100.00</balance> 
    <link rel="deposit" href="/account/12345/deposit" /> 
    <link rel="withdraw" href="/account/12345/withdraw" /> 
    <link rel="transfer" href="/account/12345/transfer" /> 
    <link rel="close" href="/account/12345/close" /> 
</account>

Além disso, já li várias vezes que fazer isso é muito importante pra várias coisas, entre elas pra permitir que a API consiga evoluir facilmente sem quebrar clients antigos.

Acontece que eu não consigo entender quais são os reais benefícios de fazer isso. Basicamente o client não vai decidir por si só quais chamadas fazer baseado nesses links, de qualquer forma temos que colocar "hardcoded" lá o que pode ser feito em seguida.

Assim, qual a real importância de usar HATEOAS e quais benefícios temos a partir do seu uso?

1
  • No momento não posso dar uma resposta abrangente, mas pense numa simples página web: o client (browser) pode não decidir por si só quais chamadas fazer, mas o usuário pode - é só clicar nos links! O fato das páginas web usarem HATEOAS permite que tanto os servidores (i.e. o que implementa a lógica da aplicação, e que serve páginas web segundo esse princípio) podem variar (não importa se é Java, .NET, PHP, Python...) quanto os clientes que consomem as mesmas também podem (não importa se é Firefox, Chrome, IE...), de forma independente um do outro. A ideia geral é essa.
    – mgibsonbr
    5/02/2015 às 1:25

4 Respostas 4

34

A característica HATEOAS é, nas palavras do seu autor, "design na escala de décadas" e "muitas das suas restrições são diretamente opostas à eficiência em curto prazo". Ou seja, é algo aplicável a softwares/plataformas de propósito mais geral, destinados a sobreviver por um longo período de tempo, apesar das evoluções da tecnologia.

O melhor exemplo de aplicação prática do HATEOAS é o protocolo HTTP, no qual uma variedade de servidores podem se comunicar com uma variedade de clientes, e ambos podem evoluir de forma independente uns dos outros. Numa aplicação web, por exemplo, não apenas as estruturas das páginas são informadas pelo servidor (e renderizadas no browser) como também vem a indicação de quais ações são possíveis a partir daquela página - representadas por meio de URLs a serem consultadas (sejam hiperlinks, destinos de formulários, ou outra coisa). Uma mudança no servidor (digamos, a inclusão de um novo campo na página) não demanda uma mudança no cliente, pois quaisquer ações relacionadas a ela estarão representadas na forma de hipermídia, e o browser sabe como invocá-las via o próprio protocolo HTTP.

Você está certo quando diz que os links devem representar o que pode ser feito em seguida. O significado disso, entretanto, é que é o ponto chave: essa combinação dados + link representam o estado do sistema, ou do recurso dentro do sistema. Usando o mesmo exemplo citado, se a conta bancária está no negativo, então não se pode retirar dela ou transferir a partir dela, somente depositar mais dinheiro nela:

<?xml version="1.0"?>
<account>
    <account_number>12345</account_number>
    <balance currency="usd">-25.00</balance>
    <link rel="deposit" href="/account/12345/deposit" />
</account>

Isso tem pelo menos dois significados práticos:

  • O servidor não precisa manter registro de quem é o cliente que está acessando, nem em que estado ele está: o próprio cliente sabe que as únicas transições possíveis são aquelas para as quais existe um link disponível;
  • O cliente não precisa implementar nenhuma lógica customizada para descobrir quais ações são possíveis baseadas no estado atual do recurso (ex.: verificar se o saldo é ou não positivo, e com base nisso determinar se os links para retirar ou transferir devem ou não ser exibidos/habilitados). Os próprios links já dizem - pela sua presença ou ausência - o que pode ou não ser feito.

Quanto à sua alegação de que "o client não vai decidir por si só quais chamadas fazer baseado nesses links", de fato, não vai, pelo menos não sem que alguma ação seja feita por parte do usuário. Mas não é essa a única razão pela qual o servidor se comunicou com o cliente, para permitir que o usuário fizesse alguma coisa? Se a próxima chamada já pudesse ser determinada segundo alguma lógica automatizada, não precisava do controle vir pro cliente e ele fazer uma nova requisição depois disso, bastaria o próprio servidor decidir e fazer isso lá mesmo...

hardcoding

Essa questão do que colocar hardcoded e do que deixar genérico é justamente o que diferencia um design para longo prazo de um para curto. Se você está desenvolvendo um único servidor para se comunicar com um único [tipo de] cliente, então não faz sentido a princípio usar REST, muito menos usar HATEOAS! Apenas se você prevê que múltiplos clientes serão desenvolvidos com o tempo, e todos têm de ser compatíveis com o seu servidor, é que essa metodologia se aplica.

A questão toda é de evolução: se na especificação do seu client você determina que "deve haver uma tela para representar uma conta bancária, com um campo pro número e outro pro saldo, e botões para as ações 'depositar', 'retirar', 'transferir' e 'fechar'", nada impede que múltiplas implementações do seu client sejam feitas. Entretanto, se no futuro você decide incluir um campo "agência", ou você terá que torná-lo opcional (para não quebrar os clients existentes) ou terá que atualizar a especificação do client (automaticamente tornando todos os existentes incompatíveis com sua versão do server). A evolução do servidor fica atrelada à evolução dos clientes...

No caso de um campo, como no exemplo acima, não existe solução fácil: afinal, a semântica por trás dos dados representados ainda precisa ser acordada entre clientes e servidores, e isso tem de ser feito "out-of-band" (como exemplo, cada tag HTML possui uma semântica precisa, e espera-se tanto que os browsers renderizem/implementem ela corretamente quando que os servidores as enviem com uma expectativa correta do que será apresentado ao usuário).

Mas no caso das ações, no sentido de "coisas que podem ser requeridas posteriormente do servidor", é mais simples estabelecê-las de uma forma genérica do que colocá-las também hardcoded na especificação. É claro, isso presume alguma forma de comunicar ao usuário qual é a semântica da mesma (apareceu um link novo, mas o que exatamente ele faz?). Isso pode ser feito ou de forma genérica (um texto, ícone ou tooltip acompanha o link) ou também demandar uma mudança no client (se é uma ferramenta automatizada que está consumindo sua API REST, não há saída a não ser adaptá-la para se beneficiar da possibilidade nova que surgiu).

Importância e Benefícios

Infelizmente, não tenho conhecimento nem experiência suficiente para opinar sobre isso. A grande maioria dos softwares que fazemos busca eficiência em curto prazo, e a forma mais comum de evolução é "jogar fora e começar do zero"... Não apenas é raro termos prazo e orçamento para projetar para o longo prazo, como também é relativamente raro haver o interesse na interoperabilidade com sistemas de terceiros (o servidor da minha empresa tem de ser acessado pelo client da minha empresa!). E quanto surge a necessidade de uma API, ela normalmente é destinada a alimentar um processo automatizado, que precisa tomar uma decisão em relação ao próximo passo a executar, e portanto um "conhecimento" da semântica por trás das ações disponíveis.

Por essas razões, eu pessoalmente não vejo muito benefício em se seguir os princípios REST e HATEOAS à risca; talvez com mais experiência em projetos maiores, minha opinião mude, e eu possa dar uma resposta mais completa e embasada. No momento, só posso responder com uma outra pergunta: você está preparado para o momento em que seu serviço evoluir? Como pretende evitar que todos os clients do mesmo quebrem quando isso acontecer?

3

Não é um padrão que me agrada, pode ter certeza que implementar isso vai deixar seu desenvolvimento no mínimo 20% mais lento, também mais poluido, veja uma implementação em Spring onde você retornaria a entidade pura, você retorna um "Resource" da entidade ou seja, tem trabalho de criar uma classe secundaria, na hora de receber o dado também recebe com uma camada a mais, ia demorar mais pra fazer e deixar o codigo mais poluído, e não me agrada a idéia de misturar a documentação da API com os dados que estão sendo trafegados, a documentação é algo que na minha opnião é melhor estar separada em um documento, gera uma poluição amais nos seus dados, imagine uma lista com 30 dados por exemplo cada um com 5 links, seria um problema indentificar um erro nesse JSON ou XML, já o que mas me faz ir contra esse padrão são os beneficios dele, não vejo nenhum quase, exemplo:

<link rel="close" href="/account/12345/close" /> 

Aqui o front iria trabalhar com o parametro que esta dentro do HREF, um beneficio seria ficar desacoplado desse conteudo, se ele fosse alterado não teria nenhuma modificação no client, porém e se estamos pensando em alterar as rotas da aplicação teriamos que pensar que os atributos podem ser alterados também como por exemplo ao invés de "close", poderia virar "exit" por exemplo, e isso estaria hardcoded no client também, causaria problema da mesma forma, e complicaria ainda mais a correção do problema, a documentação teria que existir de qualquer forma, trabalhar substituindo a documentação por esse padrão, daria muito mais problema do que solução, e se a documentação vai ter que existir de qualquer forma sinceramente não vejo beneficio nenhum nisso.

Existem coisas parecidas como por exemplo pra quem ja trabalhou com Web Service deve conhecer WSDL, onde é uma especie de documentação do webservice, só que a utilidade é extrema, o java tem recursos que ja converte isso em classes, além disso é um arquivo só para documentação, não mistura dado com documento. Assim então hoje é algo que eu jamais usaria em nenhum projeto meu nem a curto e muito menos a longo prazo, acho que iria prejudicar muito o projeto com pouco beneficio, mas se por exemplo desenvolverem uma hora ai uma solução que le um rest hateoas e ja faz um client automaticamente, ai a coisa pode começar a mudar, e a produtividade começar a vir com esse modelo ai, mas hoje eu não usaria realmente, ha quem fale muito bem desse padrão mas eu realmente não consigo.

1

O que temos hoje na maioria dos serviços são implementações erradas do conceito de REST, tanto que tem uma vertente que tenta corrigir isso chamando as API's que realmente buscar ser REST de Hypermedia API.

O erro está ai

de qualquer forma temos que colocar "hardcoded" lá o que pode ser feito em seguida.

O servidor deve ter a liberdade de gerenciar seus recursos da forma mais apropriada, instruindo o cliente como montar as URL para acessar determinado recurso (que se for "hardcoded" pode ser considerado como um RPC).

Em uma tradução livre das palavras do Roy Fielding:

Uma API REST deve ser usada sem nenhum conhecimento além da URI inicial e um conjunto de tipos de mídia padronizados. A partir desse ponto toda transição de estado deve ser guiado pelo cliente pelas escolhas providas pelo servidor que estão presentes nas representações recebidas ou implícitas pela manipulação do usuário dessas representações. As transições podem ser determinadas (ou limitadas) pelo conhecimento do cliente dos tipos de mídia e mecanismos de comunicação de recursos, ambos podendo ser melhorados on-the-fly.

É um assunto complexo, mas você pode extrair mais informações no blog do Roy Fielding: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

--

Recomendo essa apresentações:

E esse artigo "Ninguém entende REST" http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http

1
  • Concordo! Quando as pessoas pensam em "API REST" elas pensam numa API estável, que pode ser usada por processos automatizados para realizar tarefas sem intervenção humana (e que portanto seriam "quebrados" caso a API mudasse sem aviso), quando originalmente esse conceito descrevia algo bem diferente...
    – mgibsonbr
    23/02/2015 às 16:49
0

Eu acho sem sentido essa idea de HATEOAS.

Se eu adicionar/alterar/remover um método/url da API, o implementador precisa conhecer o que foi alterado, e como chamá-lo, a "API CLiente" não saberá simplesmente navegar na estrutura descrita. O que vai ler isso será um sistema, e não um usuário com inteligência de ler um link e saber o que fazer com ele.

A GRANDE promessa é a de pseudo-documentar a API, porém, existem alternativas muito melhores para tal finalidade.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .