Qual é a necessidade de 'descoberta' em uma API REST quando os clientes não são avançados o suficiente para usá-la de qualquer maneira?

As várias palestras que assisti e os tutoriais que escaneei no REST parecem enfatizar algo chamado 'descoberta'. Para meu entendimento limitado, o termo parece significar que um cliente deve poder acessar http://URL- e obter automaticamente uma lista de coisas que ele pode fazer.

O que estou tendo problemas para entender - é que 'clientes de software' não são seres humanos. São apenas programas que não têm o conhecimento intuitivo para entender o que exatamente fazer com os links fornecidos. Somente as pessoas podem ir a um site e entender o texto e os links apresentados e agir sobre ele.

Então, qual é o objetivo da descoberta, quando o código do cliente que acessa essas URLs detectáveis ​​não pode realmente fazer nada com ele, a menos que o desenvolvedor humano do cliente realmente experimente os recursos apresentados? Isso parece exatamente a mesma coisa que definir o conjunto de funções disponíveis em um manual de Documentação, apenas de uma direção diferente e envolvendo mais trabalho para o desenvolvedor. Por que essa segunda abordagem de pré-definição do que pode ser feito em um documento externo aos recursos reais do REST é considerada inferior?

A necessidade de descoberta pode não ser relevante, mas os links que permitem a descoberta servem a mais propósitos. O mais importante deles, a meu ver, é que fornecer URIs completos nas respostas ao cliente significa que nenhum cliente precisará "compor" um URI. Isso significa que nenhum cliente precisará de conhecimento sobre como os URIs estão estruturados. E isso, por sua vez, permite que os desenvolvedores do servidor alterem o esquema de URI sempre que adequado, pois não precisam considerar que clientes mais antigos ainda dependem de uma maneira antiga de estruturar URIs.

"Clientes" podem não ser avançados o suficiente para usá-lo, mas os usuários dos clientes podem. Afinal, um cliente pode ser algo tão simples quanto um navegador da web. A capacidade de descoberta tem como objetivo permitir que as pessoas aprendam e usem a API .

Por exemplo, Jenkins (o servidor de IC) tem uma interface semelhante a REST. Vá para qualquer página, poste a URL com "/ api" e você verá uma página descrevendo tudo o que você pode fazer. Isso torna o aprendizado da API trivial. Por exemplo, http://ci.jruby.org leva você ao servidor jenkins do jruby e http://ci.jruby.org/api leva você à API dessa página específica.

Há um tempo, tive o prazer de trabalhar com uma API que tinha documentação muito, muito difícil de entender.

Depois que eu consegui obter uma resposta real do servidor, foi possível comparar a documentação com a resposta do servidor e usá-la para decifrar a documentação (e sim, decifrar que era o termo certo). O problema era que, se uma solicitação fosse enviada ao servidor que não estivesse exatamente correta de acordo com as especificações, você apenas receberia um erro e, com a documentação ilegível, descobrir como enviar as solicitações corretas era quase impossível. Também havia versões diferentes da documentação da API que não concordavam entre si e provavelmente não concordavam com a própria API; isso não ajudou.

Se houvesse um comando que eu pudesse enviar ao servidor, retornando uma lista de todos os comandos possíveis e como exatamente enviá-los, isso teria sido extremamente útil. A capacidade de descoberta não é apenas para clientes, também é útil para desenvolvedores de software.

NOTA: Não sou especialista no assunto, mas passei por um processo semelhante de tentar conciliar as diferentes nuances das interpretações das pessoas sobre "REST" há alguns anos, e esse é o que eu aprendi ao analisar o assunto. Tempo.

A meu ver, isso deriva da hipermídia de Roy Fielding como o mecanismo do estado do aplicativo, conhecido como "HATEOAS", que então se torna um facilitador da idéia de uma "rede semântica".

Então ... basicamente, e novamente como eu o entendo, você torna seu aplicativo RESTful basicamente auto-descrito, de modo que o consumidor não precisa ter conhecimento prévio de um contrato formal para consumir seu conteúdo / funcionalidade. Eles podem se envolver a partir de um ponto de extremidade raiz padrão e seguir links contextualmente relevantes que o aplicativo fornece à medida que o consumidor interage. O consumidor, é claro, pode ser uma pessoa ou um agente sistêmico.

Se você está apenas usando "REST" para URLs bonitas mapeadas para operações CRUD das quais um consumidor deve ter conhecimento prévio e chamadas de acordo com um contrato conhecido, Roy Fielding consideraria que não é verdadeiramente RESTful.

Isso não quer dizer que uma configuração de serviço RPC com sabor REST não possa ser útil / uma melhoria em relação a um modelo RPC mais elaborado e adequado para uso limitado / controlado, mas os profissionais da linha de frente o encaram e consideram degenerado / não é realmente REST.