Visão geral do REST. Parte 2: Comunicação entre cliente e servidor

Parte 1: O que é REST Nesta parte veremos mais de perto como ocorre a comunicação entre o cliente e o servidor. Ao longo do caminho, revelaremos novos termos e daremos explicações sobre eles. Para deixar tudo claro, analisaremos a comunicação cliente-servidor usando o exemplo de alguma aplicação RESTful. Digamos que estamos desenvolvendo uma aplicação web capaz de armazenar informações sobre clientes e seus pedidos. Aqueles. nosso sistema é capaz de manipular algumas entidades: criá-las, editá-las, excluí-las e fornecer informações sobre elas. Essas entidades serão:

• clientes - clientes;
• pedidos - pedidos de clientes;
• itens - mercadorias.

Na arquitetura REST, os clientes enviam solicitações ao servidor para obter ou modificar dados, e os servidores enviam respostas aos clientes às suas solicitações.

solicitações de

As solicitações dos clientes quase sempre são feitas por HTTP. Em geral, as solicitações HTTP consistem em vários componentes:

• Método HTTP;
• título;
• URI;
• corpo da solicitação.

Abaixo veremos cada parte componente com mais detalhes.

URI e recursos

Os dados que os clientes obtêm ou modificam por meio de solicitações são chamados de recursos. A base da interação cliente-servidor é a manipulação de recursos. Recursos em REST são qualquer coisa que possa receber um nome. De certa forma, são como classes em Java. Em Java podemos criar uma classe para qualquer coisa. É a mesma coisa em REST – um recurso pode ser qualquer coisa: um usuário, um documento, um relatório, um pedido. Tudo isso pode ser uma abstração de alguma entidade ou algo concreto, por exemplo, um arquivo - uma imagem, um vídeo, uma animação, um arquivo PDF. Para nosso exemplo, temos 3 recursos:

• clientes - clientes;
• pedidos - pedidos de clientes;
• itens - mercadorias.

Os clientes enviam solicitações para os chamados endpoints ou endpoints. Simplificando, um endpoint é algo como um endereço na rede. Para ir mais fundo, um endpoint é um URI : uma sequência de caracteres que identifica um recurso abstrato ou físico. Identificador Uniforme de Recursos - um identificador unificado de recursos. Às vezes, o endpoint, ou URI, é chamado de caminho – o caminho para um recurso. Para os fins deste artigo, usaremos o termo URI. Cada recurso específico deve ter um URI exclusivo. A responsabilidade de garantir que cada recurso sempre tenha seu próprio URI recai sobre os ombros do desenvolvedor do servidor. No nosso exemplo, somos os desenvolvedores, então faremos da maneira que sabemos. Assim como em um banco de dados relacional costuma-se definir a chave primária para um determinado ID numérico, no REST cada recurso possui seu próprio ID. Muitas vezes acontece que o ID de um recurso em REST corresponde ao ID do registro no banco de dados no qual as informações sobre esse recurso estão armazenadas. URIs REST geralmente começam com a forma plural de um substantivo que descreve algum recurso. Por exemplo, da palavra clientes. A seguir, um ID é indicado através de uma barra - o identificador de um cliente específico. Exemplos:

• /clients - URI de todos os clientes existentes;
• /clients/23 - URI de um cliente específico, nomeadamente o cliente com ID=23;
• /clients/4 - URI de um cliente específico, nomeadamente o cliente com ID=4.

Mas isso não é tudo. Podemos estender o URI adicionando pedidos a ele:

• /clients/4/orders — URI de todos os pedidos do cliente nº 4;
• /clients/1/orders/12 - URI do pedido nº 12 do cliente nº 1.

Se continuarmos esta cadeia e adicionarmos mercadorias, obteremos:

• /clients/1/orders/12/items — URI da lista de todos os produtos do pedido nº 12 feita pelo cliente nº 1.

Com os níveis de aninhamento, o segredo é tornar os URIs intuitivos.

Método HTTP

Método HTTP (Método HTTP em inglês) é uma sequência de quaisquer caracteres, exceto controles e separadores, que indica a operação principal em um recurso. Existem vários métodos HTTP comuns. Listamos aqueles que são usados ​​com mais frequência em serviços RESTful:

• GET - utilizado para obter informações sobre um recurso específico (via ID) ou um conjunto de recursos;
• POST - usado para criar um novo recurso;
• PUT - utilizado para alterar um recurso (via ID);
• DELETE - usado para excluir um recurso (via ID).

Títulos

As solicitações, assim como as respostas, contêm cabeçalhos HTTP. Eles enviam informações adicionais sobre a solicitação (ou resposta). Cabeçalhos são pares de valores-chave. Você pode ler a lista dos títulos mais comuns na página da Wikipedia . Com REST, os clientes geralmente podem enviar um cabeçalho Accept em suas solicitações ao servidor. É necessário informar ao servidor em que formato o cliente espera receber uma resposta dele. Várias opções de formato são apresentadas na chamada lista de tipos MIME. MIME (Multipurpose Internet Mail Extensions) é uma especificação para codificar informações e formatar mensagens para que possam ser enviadas pela Internet. Cada tipo MIME consiste em duas partes, separadas por uma barra: um tipo e um subtipo. Exemplos de tipos MIME para diferentes tipos de arquivos:

• texto - texto/simples, texto/css, texto/html;
• imagem - imagem/png, imagem/jpeg, imagem/gif;
• áudio - áudio/wav, áudio/mpeg;
• vídeo - vídeo/mp4, vídeo/ogg;
• aplicação - aplicação/json, aplicação/pdf, aplicação/xml, aplicação/octeto-stream.

No total, a solicitação pode ter o seguinte cabeçalho:

Accept:application/json

Este cabeçalho informa ao servidor que o cliente espera receber uma resposta no formato JSON.

Solicitar corpo

Uma mensagem enviada pelo cliente ao servidor. Se uma solicitação tem corpo ou não, depende do tipo de solicitação HTTP. Por exemplo, as solicitações GET e DELETE normalmente não contêm nenhum corpo de solicitação. Mas PUT e POST podem conter: é tudo uma questão de propósito funcional do tipo de solicitação. Afinal, para receber dados e excluí-los pelo id (que é transmitido na URL), não é necessário enviar dados adicionais ao servidor. Mas para criar um novo recurso (solicitação POST), você precisa transferir esse recurso. O mesmo vale para modificar um recurso existente. Em REST, os formatos XML ou JSON são usados ​​com mais frequência para transmitir o corpo da solicitação. O formato mais comum é JSON. Suponha que queiramos enviar uma solicitação ao servidor e nele criar um novo recurso. Se você se lembra, como exemplo, analisamos um aplicativo que gerencia pedidos de clientes. Digamos que queremos criar um novo cliente. No nosso caso, armazenamos as seguintes informações sobre os clientes: Nome Email Número de telefone Então o corpo dessa solicitação poderia ser o seguinte JSON:

{
  "name" : "Amigo",
  "email" : "amigo@jr.com",
  "phone" : "+7 (191) 746-43-23"
}

Juntando solicitações

Portanto, vimos em que pode consistir uma solicitação de cliente. Vamos agora dar alguns exemplos de consultas com descrições

Respostas

Digamos algumas palavras sobre as respostas do servidor. A resposta geralmente consiste nas seguintes partes:

• Código de resposta;
• cabeçalhos;
• corpo de resposta.

Em geral, os cabeçalhos de resposta não são muito diferentes dos cabeçalhos de solicitação. Além disso, alguns cabeçalhos são usados ​​tanto em respostas quanto em solicitações. Acho que tudo está claro também com o corpo da resposta. O órgão geralmente retorna informações solicitadas pelo cliente. As informações podem ser retornadas no mesmo formato JSON para solicitações GET. Mas a última parte é um pouco mais interessante.

Códigos de resposta HTTP

Vamos dar uma olhada mais de perto nos códigos de resposta HTTP. Aqui está uma citação da Wikipedia: O código de status HTTP faz parte da primeira linha da resposta do servidor para solicitações por meio do protocolo HTTP. É um número inteiro com três dígitos decimais. O primeiro dígito indica a classe da condição. O código de resposta geralmente é seguido por uma frase explicativa em inglês separada por um espaço, que explica à pessoa o motivo dessa resposta específica. Exemplos:

• 201 Criado;
• 401 não autorizado;
• 507 Armazenamento insuficiente.

O cliente aprende com o código de resposta sobre os resultados de sua solicitação e determina quais ações tomar em seguida. Os códigos de resposta são divididos em vários grupos:

• 1ХХ - informativo;
• 2ХХ - informar sobre casos de aceitação e processamento bem-sucedido de solicitação de cliente;
• 3XX - informar ao cliente que para concluir a operação com sucesso é necessário realizar outra requisição, normalmente utilizando uma URI diferente;
• 4ХХ - erro do cliente. Por exemplo, uma solicitação construída incorretamente ou o conhecido código 404 Not Found, que pode ocorrer quando um cliente solicita um recurso inexistente;
• 5ХХ - erro do servidor. Retornado ao cliente se a operação falhar devido a falha do servidor.

Você pode ler mais sobre todos os códigos aqui . Parte 1: O que é REST Parte 3: Criando um serviço RESTful no Spring Boot