Muito do que pensei que sabia sobre REST está aparentemente errado - e não estou sozinho. Esta pergunta tem uma longa introdução, mas parece necessária porque a informação está um pouco dispersa. A questão real vem no final se você já estiver familiarizado com este tópico.
Desde o primeiro parágrafo das APIs REST de Roy Fielding deve ser orientado por hipertexto , está bastante claro que ele acredita que seu trabalho está sendo amplamente mal interpretado:
Estou ficando frustrado com o número de pessoas chamando qualquer interface baseada em HTTP de API REST. O exemplo de hoje é a API REST SocialSite . Isso é RPC. Grita RPC. Há tanto acoplamento em exibição que deveria receber uma classificação X.
Fielding segue listando vários atributos de uma API REST. Alguns deles parecem ir contra a prática comum e os conselhos comuns sobre SO e outros fóruns. Por exemplo:
Uma API REST deve ser inserida sem nenhum conhecimento prévio além do URI inicial (marcador) e um conjunto de tipos de mídia padronizados que são apropriados para o público-alvo (ou seja, deve ser entendido por qualquer cliente que possa usar a API). ...
Uma API REST não deve definir nomes ou hierarquias de recursos fixos (um acoplamento óbvio de cliente e servidor). ...
Uma API REST deve gastar quase todo o seu esforço descritivo na definição do (s) tipo (s) de mídia usado (s) para representar recursos e direcionar o estado do aplicativo, ou na definição de nomes de relações estendidas e / ou marcação habilitada para hipertexto para tipos de mídia padrão existentes. ...
A ideia de "hipertexto" desempenha um papel central - muito mais do que a estrutura URI ou o que os verbos HTTP significam. "Hipertexto" é definido em um dos comentários:
Quando eu [Fielding] digo hipertexto, quero dizer a apresentação simultânea de informações e controles de forma que a informação se torne a disponibilidade por meio da qual o usuário (ou autômato) obtém escolhas e seleciona ações. A hipermídia é apenas uma expansão sobre o que o texto significa incluir âncoras temporais dentro de um fluxo de mídia; a maioria dos pesquisadores abandonou a distinção.
O hipertexto não precisa ser HTML em um navegador. As máquinas podem seguir links quando entendem o formato dos dados e os tipos de relacionamento.
Eu estou supondo neste ponto, mas os dois primeiros pontos acima parecem sugerir que a documentação da API para um recurso Foo que se parece com o seguinte leva a um acoplamento estreito entre cliente e servidor e não tem lugar em um sistema RESTful.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
Em vez disso, um agente deve ser forçado a descobrir os URIs para todos os Foos, por exemplo, emitindo uma solicitação GET contra / foos. (Esses URIs podem seguir o padrão acima, mas isso não vem ao caso.) A resposta usa um tipo de mídia que é capaz de transmitir como acessar cada item e o que pode ser feito com ele, dando origem ao terceiro ponto acima . Por esse motivo, a documentação da API deve se concentrar em explicar como interpretar o hipertexto contido na resposta.
Além disso, toda vez que um URI para um recurso Foo é solicitado, a resposta contém todas as informações necessárias para um agente descobrir como proceder, por exemplo, acessando recursos associados e pais por meio de seus URIs ou tomando uma ação após a criação / exclusão de um recurso.
A chave para todo o sistema é que a resposta consiste em hipertexto contido em um tipo de mídia que, por sua vez, transmite ao agente opções para prosseguir. Não é diferente da maneira como um navegador funciona para humanos.
Mas este é apenas meu melhor palpite neste momento particular.
Fielding postou um follow-up no qual ele respondeu às críticas de que sua discussão era muito abstrata, sem exemplos e rica em jargões:
Outros tentarão decifrar o que escrevi de maneiras mais diretas ou aplicáveis a alguma preocupação prática de hoje. Provavelmente não irei, porque estou muito ocupado lutando com o próximo tópico, me preparando para uma conferência, escrevendo outro padrão, viajando para algum lugar distante ou apenas fazendo as pequenas coisas que me fazem sentir que mereci meu salário.
Então, duas perguntas simples para os especialistas em REST com uma mentalidade prática: como você interpreta o que Fielding está dizendo e como você o coloca em prática ao documentar / implementar APIs REST?
Edit: esta pergunta é um exemplo de como pode ser difícil aprender algo se você não tiver um nome para o que está falando. O nome nesse caso é "Hipermídia como o mecanismo do estado do aplicativo" (HATEOAS).