A descoberta em HATEOAS requer que as informações sejam legíveis por máquina ou podem ser legíveis para humanos?

5

Estou tentando entender os conceitos de HATEOAS (Hipermídia como o mecanismo do estado do aplicativo) no REST. Os seguintes foram muito úteis:

O que HATEOAS oferta para descoberta e desacoplamento além da capacidade de alterar sua estrutura de URL mais ou menos livremente?

APIs REST devem ser orientadas por hipertexto (de Roy Fielding ele mesmo)

Com base neles, eu entendo que o HATEOAS não está apenas fornecendo links para dizer ao cliente quais são as próximas ações válidas, mas também fornecendo informações sobre os métodos válidos que podem ser aplicados a um recurso e o formato dos dados. sendo passado em ambas as direções entre o cliente e o servidor.

É o formato de dados com o qual estou tendo problemas. Roy Fielding menciona a definição de novos tipos de mídia para descrever os formatos de dados. Se novos tipos de mídia tiverem que ser criados para cada API que alguém criar, haverá centenas de milhares de tipos de mídia de uso único definidos.

Para contornar esse problema, alguém sugeriu o uso do tipo de mídia HAL ( Hypertext Application Language ) para APIs RESTful. O HAL inclui o conceito de CURIEs, prefixos para nomes de relações que se expandem em URLs que apontam para documentação.

Por exemplo,

"_links": {
  "curies": [
    {
      "name": "doc",
      "href": "http://haltalk.herokuapp.com/docs/{rel}",
      "templated": true
    }
  ],

  "doc:latest-posts": {
    "href": "/posts/latest"
  }
}

Aqui, o nome da relação é doc:latest-posts , em que doc é uma CURIE que se expande para http://haltalk.herokuapp.com/docs/ e http://haltalk.herokuapp.com/docs/latest-posts apontará para a documentação sobre o recurso de últimas publicações (observe que a URL para o recurso de últimas publicações em si, ao contrário da documentação sobre isso, é /posts/latest )

Isso parece ser uma boa maneira de os desenvolvedores do lado do cliente aprenderem sobre cada recurso fornecido pela API. Mas ter um link automático para documentação legível humana satisfaz os requisitos de detecção de HATEOAS? Ou as informações que descrevem os formatos de dados necessários para cada recurso devem ser legíveis por máquina (por exemplo, um tipo de mídia personalizado para a API)?

    
por Simon Tewsi 17.01.2016 / 04:43
fonte

1 resposta

2

Como você apontou, Roy Fielding escreveu um artigo interessante em seu blog. E este parágrafo resume muito bem "How to HATEOAS":

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

Então, sim, a HATEOAS depende de fornecer links para os clientes para direcioná-los ao aplicativo. Um exemplo típico é, como parte de um aplicativo bancário, uma conta bancária em que você tem um link para retirar e um outro link para fazer um depósito. Se seu saldo for negativo, o link para retirada desaparecerá. Isso é HATEOAS: você fornece links para ajudar o cliente.

Mas espere um minuto. No parágrafo citado, Fielding fala sobre descriptive effort , media type e out-of-band information ... interessante :-)! Na verdade, a HATEOAS não está apenas fornecendo links, porque não é suficiente para um cliente ter apenas links sem sentido. Como o cliente deveria saber os verbos para invocar ao seguir um link? (GET / POST / PUT?) ... Como o cliente deveria saber os dados para passar como parâmetro ao seguir um link? Se o cliente não souber essas informações, é simples: o seu cliente depende de out-of-band information (e isso é baaaaaad!)

Aí vem a parte interessante: como o cliente pode obter essa informação? Resposta: através de self-descriptive message e media-type usado! É assim que você faz HATEOAS: você totalmente (não apenas fornecendo links!) Direciona o cliente com links e mensagens auto-descritivas.

Dependendo do seu aplicativo, você pode ter que definir seu próprio tipo de mídia para descrever sua mensagem com precisão. Alguns outros existem, s eles são chamados de "formato hipermídia". HAL é um deles, mas tem algumas limitações. Uma comparação desatualizada pode ser encontrada aqui: link

Pessoalmente, sugiro que você dê uma olhada no Hydra, que provavelmente seria um padrão do W3C e tem muitos recursos. Por exemplo, você pode definir quais operações são possíveis em um link (= quais verbos usar, quais dados passar como parâmetro, se necessário ou não, etc ...). Algumas apresentações agradáveis podem ser encontradas lá: link

Para concluir: Eu diria que o HATEOAS está relacionado a legibilidade por máquina. Ao autodescrever a mensagem, você permite que qualquer máquina entenda sua API. Porque o legível humano pode envolver conhecimento fora de banda e isso é tipicamente o que não é RESTful (nem compatível com HATEOAS).

    
por 19.01.2016 / 15:25
fonte

Tags