"E você acreditou nele?" O ombudsman do casco disse reprovadoramente. "Bem, o que você acha, eu teria levado esses pesos sem a sua permissão?"
"Então você pegou os pesos?" Gritou Ostap. Porque?
- Panikovsky disse que eles são ouro.
Ostap olhou para Panikovsky. Só agora ele percebeu que, sob o paletó, não havia mais do que uma camisa de cinquenta dólares e, a partir daí, o olhar nu de Deus olhou para a luz do dia. Sem uma palavra, o grande combinador caiu em uma cadeira. Ele balançou, pegando as mãos no ar. Então estrondos vulcânicos saíram de sua garganta, lágrimas escorreram de seus olhos e risos, que afetaram todo o cansaço da noite, toda a decepção na luta contra Koreiko, tão pateticamente parodiada por seus irmãos de leite.
Com esse fragmento dos clássicos, eu gostaria de prefaciar a tradução das postagens de blog de Roy T. Fielding. As APIs REST devem ser orientadas por hipertexto. Agradecimentos especiais a
habr.com/users/arthuriantech pelo link para o material.
Esta semana em Habré foi marcada como a semana da API REST (completa). Nesse sentido, sempre fiquei confuso com a presença do prefixo REST nesse termo. E, como se viu, não apenas eu. Hoje vou ler eu mesmo e convidar todos a descobrir o que Roy T. Fielding pensou sobre isso em 2008. Obviamente, alguém rasteja nervosamente em um banquinho e diz: diga a Roy, Benya conhece a API REST. No entanto, começaremos.
Estou desanimado com o pensamento de quantas pessoas chamam qualquer interface com base na API REST do protocolo HTTP. O exemplo de hoje é a API REST SocialSite. Este é um RPC. Este é um RPC flagrante. Isso demonstra vínculos tão duros que é hora de ele atribuir a categoria de pornografia pesada.
O que precisa ser feito para que eles entendam que o hipertexto é um elemento necessário na arquitetura REST? Em outras palavras, se o mecanismo de estado do aplicativo (e, portanto, a API) não for baseado em hipertexto, ele não poderá ser RESTful e não poderá ser uma API REST. O ponto. Que livro devo reescrever para deixar claro?
Desenvolvedores de API, preste atenção às seguintes regras antes de chamar suas criações de API REST:
A API REST não deve depender de um protocolo de comunicação específico, embora seu mapeamento bem-sucedido para esse protocolo possa depender da disponibilidade de metadados, escolha de métodos etc. Em geral, qualquer protocolo em um esquema de URI deve permitir que qualquer esquema de URI seja usado para identificação. [O erro aqui é que a identificação não é separada da interação.]
A API REST não deve conter nenhuma alteração nos protocolos de comunicação, exceto preenchendo ou corrigindo os detalhes de bits insuficientemente definidos dos protocolos padrão, como o método PATCH HTTP ou o campo de cabeçalho Link. As soluções alternativas para implementações que não funcionam (como navegadores que são burros o suficiente para acreditar que o HTML define um conjunto de métodos HTTP) devem ser determinadas separadamente ou, pelo menos em aplicativos, com a expectativa de que a solução alternativa se torne obsoleta. [O erro aqui é que as interfaces de recursos são específicas e não universais.]
A API REST deve gastar quase todos os seus esforços descritivos na definição dos tipos de mídia usados para representar recursos e no gerenciamento do estado do aplicativo, bem como na definição de nomes estendidos de relacionamento e marcação de hipertexto para os tipos de mídia padrão existentes. Qualquer esforço despendido para descrever quais métodos usar com quais URIs de interesse deve ser totalmente definido como parte das regras de processamento para o tipo de mídia (e, na maioria dos casos, já definido pelos tipos de mídia existentes). [O erro aqui é que informações externas ao recurso controlam a interação em vez de hipertexto.]
A API REST não deve definir nomes de recursos ou espaços de nomes fixos (conectividade forte entre cliente e servidor). Os servidores devem ter liberdade para gerenciar seus próprios namespaces. Em vez disso, permita que os servidores instruam os clientes sobre como criar os URIs apropriados, por exemplo, em formulários HTML e modelos de URI, definindo essas instruções nos tipos de mídia e nos relacionamentos de referência. [O erro aqui é que a estrutura do recurso é configurada fora desse recurso, por exemplo, em um padrão específico de domínio, que na verdade é um análogo do relacionamento funcional da RPC].
A API REST nunca deve ter "digitado" recursos significativos para o cliente. Os autores das especificações podem usar tipos de recursos para descrever a implementação do servidor atrás da interface, mas esses tipos devem ser irrelevantes e invisíveis para o cliente. Os únicos tipos que são importantes para o cliente são o tipo de mídia da exibição atual e os nomes de relacionamento padronizados. [veja acima]
A API REST deve ser inserida sem nenhum conhecimento prévio que não seja o URI inicial e um conjunto de tipos de mídia padronizados adequados para o público-alvo (ou seja, o esperado no lado do cliente, que pode usar a API). A partir deste momento, todas as transições de estados de aplicativos devem ser determinadas pela escolha das opções fornecidas pelo servidor que estão presentes nas visualizações recebidas ou pelas manipulações do usuário com essas visualizações. As transições podem ser determinadas (ou limitadas) pelo conhecimento do cliente sobre os tipos de mecanismos de comunicação de mídia e recursos que podem ser aprimorados rapidamente (por exemplo, código sob solicitação). [O erro aqui é que informações externas ao recurso controlam a interação em vez de hipertexto.]
Talvez eu tenha perdido alguma coisa, mas as regras acima são essenciais para o hipertexto, que são violadas com mais freqüência na chamada API REST. Tente ficar com eles ou escolha outra palavra da moda para sua API.
Este post de Roy T. Fielding provocou uma discussão nos comentários. Proponho me familiarizar com a parte da discussão, que foi acompanhada pelas respostas do autor.
Pergunta:
Em que sentido você usa o termo "hipertexto" aqui? Preciso ler seu trabalho para entender o que você quer dizer ou há algo online que revele o significado desse conceito?
A resposta é:
Eu tenho um slide na minha palestra REST que explica o que significa hipertexto (e hipermídia).
O hipertexto tem muitas definições:
A definição inicial de Ted Nelson foi focada em documentos não lineares.
Por "hipertexto", quero dizer um documento não linear - um texto que bifurca e permite ao leitor fazer uma escolha, um documento que é fácil de ler em uma tela interativa. É geralmente aceito que essa é uma sequência de blocos de texto vinculados por links que oferecem ao leitor várias rotas. Theodore H. Nelson
Mais tarde, o hipertexto tornou-se associado a um mecanismo específico da interface do usuário.
O hipertexto é um meio de armazenamento suportado por computador no qual os documentos relacionados são exibidos com seus links em uma tela de computador de alta resolução. Jeffrey Conklin
Quando digo "hipertexto", quero dizer a apresentação simultânea de informações e controles de forma que as informações fiquem disponíveis, graças às quais o usuário (ou máquina) escolhe e escolhe ações. A hipermídia é simplesmente uma extensão do que o texto significa para incluir âncoras temporárias no fluxo de mídia; a maioria dos pesquisadores rejeitou essa distinção.
O hipertexto não precisa ser HTML para o navegador. As máquinas podem seguir os links quando entenderem o formato dos dados e os tipos de relacionamento.
Dave Johnson (autor da API criticada):
Talvez eu tenha dado uma expressão confusa. Eu nunca pretendi afirmar que as APIs RPC do OpenSocial ou SocialSite eram RESTful. Mais no meu blog rollerweblogger.org/roller/entry/the_x_rated_socialsite_api .
A resposta é:
O protocolo OpenSocial RESTful não é RESTful. Isso pode ser corrigido com alterações relativamente pequenas, mas agora apenas compacta os resultados da RPC em tipos comuns de mídia da web.
A verdadeira API RESTful se parece com hipertexto. Cada unidade de informação endereçável carrega um endereço, explicitamente (por exemplo, atributos de link e ID) ou implicitamente (por exemplo, obtido a partir da definição do tipo de mídia e estrutura de apresentação). Os resultados da consulta são representados por uma lista de links com informações resumidas, em vez de matrizes de representações de objetos (a consulta não substitui a identificação de recursos). As representações de recursos são auto-documentadas: o cliente não precisa saber se esse recurso é um OpenSocialist, porque simplesmente afeta as representações recebidas.
Pense nisso em termos de Internet. Quantos navegadores da web estão cientes da diferença entre um recurso bancário on-line e um wiki? Não é um deles. Eles não precisam saber sobre os tipos de recursos. O que eles precisam saber são as transições de estado em potencial: links e formulários e que tipo de semântica ou ação está implícita ao atravessar esses links. O navegador os apresenta como controles separados da interface do usuário, para que o usuário possa ver possíveis transições e antecipar o efeito das ações selecionadas. Os robôs podem segui-los na medida em que se sabe que as ações são seguras. Relacionamentos digitados, tipos específicos de mídia e elementos relacionados à ação fornecem a orientação necessária para agentes automatizados.
Links úteis:
1.
Versão de tradução de habr.com/us/users/arthuriantech2.
A mesma tese do velho Roy