Na linguagem REST, qual é a diferença entre um recurso e uma representação?

Meu entendimento do REST que permite modelar operações de serviço como representação de estado e transição de um estado para outro usando HTTP. Sempre entendi os recursos como representações do estado do lado do serviço até recentemente, quando li este artigo de Jimmy Bogard, que sei ser um desenvolvedor / arquiteto inteligente, bem respeitado pela comunidade. Para citar uma declaração específica dessa postagem

A representação é um pouco diferente - descreve o estado atual do recurso (quando solicitado).

Isso me deixou confuso. Qual é a opinião geralmente aceita sobre o tema?

Resposta curta

O mapa não é o territorio.

Resposta mais longa - como em qualquer outra coisa, o ponto de partida é a tese de Roy Fielding ; em particular no capítulo 5 . Para sua pergunta atual, você deseja a seção 5.2.1.

O REST é definido por quatro restrições de interface: identificação de recursos; manipulação de recursos através de representações; mensagens auto-descritivas; e hipermídia como o mecanismo do estado do aplicativo.

Recurso

A abstração principal das informações no REST é um recurso. Qualquer informação que possa ser nomeada pode ser um recurso: um documento ou imagem, um serviço temporal (por exemplo, "o clima de hoje em Los Angeles"), uma coleção de outros recursos, um objeto não virtual (por exemplo, uma pessoa) e assim por diante . Em outras palavras, qualquer conceito que possa ser o alvo da referência de hipertexto de um autor deve se encaixar na definição de um recurso. Um recurso é um mapeamento conceitual para um conjunto de entidades, não a entidade que corresponde ao mapeamento em qualquer momento específico.

Representação

Os componentes REST executam ações em um recurso usando uma representação para capturar o estado atual ou pretendido desse recurso e transferindo essa representação entre componentes. Uma representação é uma sequência de bytes, além de metadados de representação para descrever esses bytes. Outros nomes comumente usados, mas menos precisos, para uma representação incluem: documento, arquivo e entidade, instância ou variante de mensagem HTTP.

Uma representação consiste em dados, metadados que descrevem os dados e, ocasionalmente, metadados para descrever os metadados (geralmente com o objetivo de verificar a integridade da mensagem).

Então: "o clima de hoje em Los Angeles" é um recurso. As representações dos candidatos incluiriam: um documento de texto com as últimas previsões do serviço nacional de meteorologia; uma representação visual do radar meteorológico e gravação de áudio da previsão.

Um recurso é o que você está trabalhando. Por exemplo, se você possui uma API para trocar uma determinada lâmpada, o recurso é a própria lâmpada. Um recurso pode ser físico (por exemplo, lâmpada, pessoa) ou não físico (por exemplo, artigo, função, uma linha no banco de dados), um recurso pode ser primário (por exemplo, saldo) ou derivado (por exemplo, transação). Um recurso pode se referir a uma entidade específica (por exemplo, a quinta lâmpada instalada neste soquete), ou a uma função que é mapeada para entidade diferente em momentos diferentes (por exemplo, a lâmpada atualmente instalada, a lâmpada instalada em 5 de agosto de 2008) ou pode mapear para várias entidades (por exemplo, todas as lâmpadas da casa).

A representação de um recurso é a maneira como seu serviço comunica o estado do recurso, por exemplo, XML, JSON que representa o estado da lâmpada.

Na API REST, um recurso é identificado por um identificador uniforme (por exemplo, URI). Um único recurso pode ter várias representações. Na API REST HTTP, você normalmente indica a representação que deseja usar nos cabeçalhos HTTP Content-Type e Accept.

Uma das principais realizações na arquitetura do servidor cliente é que você não pode trazer o recurso para o cliente e não deve tentar fazê-lo como faz. Em vez disso, na API REST, você manipula remotamente um recurso transferindo representações do recurso. Pense assim: você não FedEx a lâmpada para que o cliente possa manipular a lâmpada diretamente, mas o serviço cria uma representação XML / JSON / protobuf / CSV da lâmpada e o cliente envia uma representação das manipulações pretendidas. O serviço manipula o estado real da lâmpada em nome do cliente ou rejeita a solicitação, digamos se o cliente não está autorizado a executar as operações na lâmpada. Isso pode parecer óbvio / dividir o cabelo, mas o importante a ser observado é que, como a representação não é o recurso em si,

Um recurso pode ser uma fatura.

Uma representação é uma fatura em um momento específico no formato JSON ou XML. Você pode obter exatamente a mesma fatura em uma data posterior, pois será o mesmo recurso, mas em um estado potencialmente diferente (cancelado, pago, etc.).

Você pega o estado atual da fatura (por exemplo: todos os dados da fatura no banco de dados) e fornece uma representação específica (por exemplo: html, xml, json) em um momento específico, para transferência para outro dispositivo (por exemplo: um navegador)