Ultimamente, tenho lido sobre a Hipermídia como o Estado do Mecanismo de Aplicativo (HATEOAS), a restrição reivindicada para tornar uma API da Web "verdadeiramente RESTful". Tudo se resume a incluir basicamente links com todas as respostas às possíveis transições que você pode fazer a partir do estado atual.
Deixe-me ilustrar o que o HATEOAS é baseado no meu entendimento - e, por favor, corrija-me se eu perder alguma coisa.
/
GET: {
"_links": {
"child": [
{ "href": "http://myapi.com/articles", "title": "articles" }
]
}
}
/articles?contains=HATEOAS
GET: {
"_items": [
{ "uri": "http://myapi.com/articles/0", "title": "Why Should I Care About HATEOAS?" },
{ "uri": "http://myapi.com/articles/1", "title": "HATEOAS: Problem or Solution?" }
],
"_links": {
"self": { "href": "http://myapi.com/articles", "title": "articles" },
"parent": { "href": "http://myapi.com/", "title": "home" }
}
}
POST: {
"title": "A New Article",
"body": "Article body",
"tags": [ "tag1", "tag2" ]
}
/articles/0
GET: {
"title": "Why Should I Care About HATEOAS?",
"body": "Blah blah blah"
"tags": [ "REST", "HATEOAS" ],
"_links": {
"self": { "href": "http://myapi.com/articles/0", "title": "article" },
"parent": { "href": "http://myapi.com/articles", "title": "articles" }
}
}
Alega-se que o HATEOAS oferece dois grandes benefícios:
Todo o serviço pode ser iniciado a partir do URI raiz, a documentação não é mais necessária.
O cliente é dissociado do servidor, que agora pode alterar livremente a estrutura do URI. Isso elimina a necessidade de versionamento da API.
Mas, na minha opinião, um serviço é muito mais do que sua estrutura de URI. Para usá-lo efetivamente, você também precisa saber:
- quais parâmetros de consulta você pode usar e seus possíveis valores
- a estrutura do JSON / XML / quaisquer documentos que você precise enviar em suas solicitações POST / PATCH / etc
- a estrutura da resposta enviada pelo servidor
- os possíveis erros que podem ocorrer
- ...
Com base no exposto, o HATEOAS resolve apenas uma pequena fração dos problemas de descoberta e acoplamento. Você ainda precisa documentar os quatro aspectos acima e os clientes ainda estarão fortemente acoplados ao servidor por causa deles. Para evitar a quebra de clientes, você ainda precisa fazer a versão da sua API.
O único benefício que ele oferece é que você pode alterar sua estrutura de URL mais ou menos livremente (a propósito, o que aconteceu com o princípio "URIs legais não mudam" ?). Meu entendimento está correto?
A única coisa que a torna uma verdadeira API REST é atender a todas as restrições, não apenas uma.
É por isso que precisamos de outras restrições, mensagem auto-descritiva, etc.
Não importa como você tente, precisará fazer a versão da sua API. Em um cliente REST, você ainda precisa saber como chegar a uma página na qual deseja fazer as coisas, quais links a seguir e quais propriedades você precisa coletar com base no vocabulário RDF que descreve a mensagem. Se você precisar substituir ou remover algo desse vocabulário, provavelmente quebrará todos os seus clientes e você precisará de uma nova versão. Portanto, acho que o REST não é algo que você deve publicar cedo (e descobrir o modelo enquanto altera constantemente a API); caso contrário, você terá várias versões. Você precisa de um modelo de domínio estável primeiro para construir ...
fonte