Utilizando HATEOAS para reduzir acoplamento e “inteligência de negócio” em aplicações cliente

Elemar Júnior

APIs robustas e bem modeladas simplificam a construção de aplicações clientes, reduzindo o acoplamento e a necessidade delas implementarem “inteligência do negócio”.

Em APIs REST, a redução de acoplamento e da necessidade de implementar “inteligência do negócio” nas aplicações clientes é obtida pela adoção de HATEOAS.

O que é HATEOAS?

Hypermedia as the Engine of Application State, ou HATEOAS, é uma “maneira” de implementar APIs REST utilizando hipermídia para indicar que ações ou navegações estão disponíveis para um determinado recurso.

As ações e a navegação são derivadas do estado do recurso e, eventualmente, da própria API. Elas são disponibilizadas para o cliente através de uma coleção de links.

{
  “custormerId”: 1, 
  “firstName”: “John”, 
  “lastName”: “Doe”, 
  ...
  
  links: []
}

Não há uma definição universalmente aceita sobre onde esta coleção de links deve ser fornecida. Há quem defenda a inclusão na representação do recurso. Outros, defendem a utilização dos cabeçalhos da “response HTTP”.

Quanto aos dados necessários em cada link,  há uma RFC (5598).

A coleção de links em uma implementação HATEOAS deveria ser suficiente para indicar que ações são suportas para um determinado recurso e, também, navegação para recursos relacionados (incluindo self).

O primeiro link da coleção deveria ser uma referência para o próprio objeto.

{
  “custormerId”: 1, 
  “firstName”: “John”, 
  “lastName”: “Doe”, 
  ...
  
  links: [{
    “rel”: “self”,
    “href”: “http://mydomain/customers/1” ]
  }]
}

Dessa forma, caso a representação do recurso “passeie” pela aplicação cliente, ou, caso ela, eventualmente, seja persistida ou compartilhada com outros contextos, em qualquer momento, seria possível determinar sua origem sem “inferências no código”.

Na eventualidade de haver mudanças nas rotas da API, endereços antigos devem redirecionar para o novo endereço.

Imagine-se concebendo uma interface para o usuário. Nela, deve ser possível alterar os dados de um recurso ou solicitar sua exclusão. Eventualmente, alguns recursos (um pedido, por exemplo) não podem ser alterados sob certas condições. Ou ainda, não podem ser excluídos. Como e onde a “lógica” para determinar as ações possíveis deve ser implementada?

{
  “custormerId”: 1, 
  “firstName”: “John”, 
  “lastName”: “Doe”, 
  ...
  
  links: [{
    “rel”: “self”,
    “href”: “http://mydomain/customers/1” ]
  },{
    “rel”: “update”,
    “href”: “http://mydomain/customers/1” ]
  },{
    “rel”: “delete”,
    “href”: “http://mydomain/customers/1” ]
  }]
}

Fornecer a lista de ações possíveis para um recurso na coleção de links permite que essa lógica seja implementada totalmente no serviço e simplifica muito a implementação da aplicação cliente. O botão “excluir”, por exemplo, estaria disponível apenas se o link correspondente estivesse na coleção.

Outra vantagem de retornar a lista de links com as ações disponíveis é que a lógica pode mudar no servidor, incluindo os endereços, sem alteração alguma no código da aplicação cliente.

Eventualmente, um recurso retornado pela API possuirá outros recursos relacionados. Por exemplo, em uma aplicação empresarial, um “cliente” possuirá uma coleção de “pedidos” que realizou.

{
  “custormerId”: 1, 
  “firstName”: “John”, 
  “lastName”: “Doe”, 
  ...
  
  links: [{
    “rel”: “self”,
    “href”: “http://mydomain/customers/1” ]
  },{
    “rel”: “update”,
    “href”: “http://mydomain/customers/1” ]
  },{
    “rel”: “delete”,
    “href”: “http://mydomain/customers/1” ]
  },{
    “rel”: “orders”,
    “href”: “http://mydomain/customers/1/orders” ]
  }]
}

A presença desses links evita que a aplicação cliente precise fazer “inferências” sobre como “chegar” em recursos relacionados, diminuindo acoplamento. Essa ação autoriza, por exemplo, a mudança na estratégia de rotas sem afetar a aplicação cliente.

{
  “custormerId”: 1,
  “firstName”: “John”,
  “lastName”: “Doe”,
  ...
  links: [ ...,
  {
    “rel”: “orders”,
    “href”: “http://mydomain/orders?customerId=1” ]
   }]
}

HATEOAS não substitui documentação

Pelos exemplos destacados é possível verificar que os links não possuem todas as informações necessárias para explorar plenamente a API. Não há indicação, por exemplo, de qual verbo HTTP deve ser utilizado para link embora fique “implícito” que self deve ser solicitado com um GET e que update deva ser solicitado com um PUT. Também não há indicação do formato do recurso (quais informações vão estar presentes e de que forma elas serão expostas).

Documentação complementar será necessária, tanto para descrever os recursos como para indicar o significado de cada rel.

Deveria implementar HATEOAS em meus serviços REST?

Não necessariamente. Sem dúvidas, HATEOAS diminui o acoplamento e a necessidade de implementar lógica de negócio na aplicação cliente. Mas, há incontáveis exemplos de APIs implementadas sem este conceito.

Também é importante destacar que HATEOAS impõe um overhead nas representações de recursos que, dependendo do volume e restrições de banda podem ser significativos.

Como deve ser feita a implementação?

A implementação de HATEOAS varia conforme a tecnologia que está sendo utilizada no backend. De qualquer forma, é importante que seja destacado que praticamente todas as tecnologias possuem pacotes e extensões que facilitam a implementação.

Em resumo

O desafio
APIs robustas devem facilitar o desenvolvimento de aplicações clientes, reduzindo o acoplamento e a necessidade escrita de “lógica de negócio”.
O insight
APIs REST podem reduzir o acoplamento e a necessidade de lógica de negócio nas aplicações clientes através da implantação cuidadosa de HATEOAS. Em suma, com a adição de uma coleção links relacionadas a cada recurso indicando ações e navegação possíveis.
Os benefícios
Aplicações clientes com baixo acoplamento com APIs e que não implementam lógica de negócio são mais baratas de implementar e manter. Além disso, autorizam melhoria no Velocity

Compartilhe este insight:

Comentários

Participe deixando seu comentário sobre este artigo a seguir:

Subscribe
Notify of
guest
0 Comentários
Inline Feedbacks
View all comments

AUTOR

Elemar Júnior
Fundador e CEO da EximiaCo atua como tech trusted advisor ajudando empresas e profissionais a gerar mais resultados através da tecnologia.

NOVOS HORIZONTES PARA O SEU NEGÓCIO

Nosso time está preparado para superar junto com você grandes desafios tecnológicos.

Entre em contato e vamos juntos utilizar a tecnologia do jeito certo para gerar mais resultados.

Insights EximiaCo

Confira os conteúdos de negócios e tecnologia desenvolvidos pelos nossos consultores:

Arquitetura de Dados

Insights de um DBA na análise de um plano de execução

Especialista em performance de Bancos de Dados de larga escala
Arquitetura de Software

Estratégias para modernização do legado

Desenvolvedor .NET/NodeJs e especialista em Kafka com experiência em startups e grandes empresas
Infraestrutura e Nuvem

Migração para a nuvem, mais do que mudança tecnológica, implica em mudança da cultura organizacional

Engenheiro de nuvem, arquiteto de software e especialista em Containers e Devops

Acesse nossos canais

Simplificamos, potencializamos e aceleramos resultados usando a tecnologia do jeito certo

EximiaCo 2022 – Todos os direitos reservados

0
Queremos saber a sua opinião, deixe seu comentáriox
()
x

Utilizando HATEOAS para reduzir acoplamento e “inteligência de negócio” em aplicações cliente

Para se candidatar nesta turma aberta, preencha o formulário a seguir:

Condição especial de pré-venda: R$ 14.000,00 - contratando a mentoria até até 31/01/2023 e R$ 15.000,00 - contratando a mentoria a partir de 01/02/2023, em até 12x com taxas.

Tenho interesse nessa capacitação

Para solicitar mais informações sobre essa capacitação para a sua empresa, preencha o formulário a seguir:

Tenho interesse em conversar

Se você está querendo gerar resultados através da tecnologia, preencha este formulário que um de nossos consultores entrará em contato com você:

O seu insight foi excluído com sucesso!

O seu insight foi excluído e não está mais disponível.

O seu insight foi salvo com sucesso!

Ele está na fila de espera, aguardando ser revisado para ter sua publicação programada.

Tenho interesse em conversar

Se você está querendo gerar resultados através da tecnologia, preencha este formulário que um de nossos consultores entrará em contato com você:

Tenho interesse nessa solução

Se você está procurando este tipo de solução para o seu negócio, preencha este formulário que um de nossos consultores entrará em contato com você:

Tenho interesse neste serviço

Se você está procurando este tipo de solução para o seu negócio, preencha este formulário que um de nossos consultores entrará em contato com você:

× Precisa de ajuda?