Visão geral do REST. Parte 1: O que é REST? Nesta parte, vamos nos aprofundar em como ocorre a comunicação entre um cliente e um servidor. Ao longo do caminho, vamos descobrir novos termos e explicá-los. Para garantir que tudo esteja claro, analisaremos a comunicação cliente-servidor usando um aplicativo RESTful como exemplo. Suponha que estejamos desenvolvendo um aplicativo da Web que armazene informações sobre clientes e seus pedidos. Em outras palavras, nosso sistema é capaz de realizar operações em determinadas entidades: criá-las, editá-las, excluí-las e exibir informações sobre elas. Essas entidades serão:
clientes (clientes)
pedidos (pedidos de clientes)
itens (produtos)
Em uma arquitetura RESTful, os clientes enviam solicitações a um servidor para recuperar ou modificar dados e, em seguida, os servidores enviam respostas aos clientes para suas solicitações.
solicitações de
As solicitações do cliente quase sempre são feitas usando o protocolo HTTP. Em geral, as solicitações HTTP consistem em vários componentes:
método HTTP
cabeçalho
URI
corpo do pedido
A seguir, consideraremos cada componente com mais detalhes.
URIs e recursos
Os dados que os clientes recebem ou modificam por meio de solicitações são chamados de recursos. A comunicação cliente-servidor tem tudo a ver com a manipulação de recursos. Em REST, os recursos são tudo o que você pode dar um nome. De certa forma, eles são como classes em Java. Em Java, podemos criar uma classe para qualquer coisa. Portanto, em REST, um recurso pode ser qualquer coisa: um usuário, um documento, um relatório, um pedido. Pode ser uma abstração de alguma entidade ou algo específico, por exemplo, uma imagem, vídeo, animação ou arquivo PDF. No nosso exemplo, temos 3 recursos:
clientes (clientes)
pedidos (pedidos de clientes)
itens (produtos)
Os clientes enviam solicitações para locais de recursos conhecidos como endpoints. Simplificando, um endpoint é como um endereço na rede. Indo mais fundo, podemos dizer que um endpoint é um URI, ou seja, uma sequência de caracteres que identifica um recurso abstrato ou físico. Identificador de recurso uniforme (URI) Às vezes, um ponto de extremidade, ou URI, é chamado de caminho, significando o caminho para um recurso. Para os fins deste artigo, usaremos o termo URI. Cada recurso específico deve ter um URI exclusivo. O desenvolvedor do servidor é responsável por garantir que cada recurso sempre tenha seu próprio URI. Em nosso exemplo, somos os desenvolvedores, então faremos da maneira que sabemos. Assim como costuma ser comum atribuir identificadores numéricos como chaves primárias em um banco de dados relacional, cada recurso também possui seu próprio ID em REST. O ID do recurso em REST geralmente corresponde ao ID do registro no banco de dados que armazena informações sobre o recurso. URIs REST geralmente começam com a forma plural de um substantivo que descreve algum recurso. Por exemplo, "
/customers — URI de todos os clientes disponíveis
/clientes/23 — URI de um cliente específico, ou seja, o cliente com ID=23
/customers/4 — URI de um cliente específico, ou seja, o cliente com ID=4.
Mas isso não é tudo. Podemos estender o URI adicionando pedidos:
/customers/4/orders — URI de todos os pedidos feitos pelo cliente nº 4
/customers/1/orders/12 — URI do pedido nº 12 feito pelo cliente nº 1.
Se continuarmos a expansão adicionando mais produtos, obtemos:
/customers/1/orders/12/items — URI da lista de todos os produtos do pedido nº 12 feito pelo cliente nº 1.
À medida que adicionamos níveis de aninhamento, o importante é tornar as URIs intuitivas.
método HTTP
O método HTTP é uma sequência de quaisquer caracteres (exceto caracteres de controle e delimitadores), que indica a operação principal que está sendo executada no recurso. Existem vários métodos HTTP comuns. Vamos listar aqueles que são mais usados em serviços RESTful:
GET — Obtenha informações sobre um determinado recurso (através de seu ID) ou sobre uma coleção de recursos
POST — Crie um novo recurso
PUT — Altere um recurso (através de seu ID)
DELETE — Excluir um recurso (através de seu ID)
Cabeçalhos
As solicitações, assim como as respostas, contêm cabeçalhos HTTP. Eles transmitem informações adicionais sobre a solicitação (ou resposta). Cabeçalhos são pares chave-valor. Você pode ver a lista dos cabeçalhos mais comuns na Wikipédia . Quanto ao REST, os clientes geralmente enviam um cabeçalho "Aceitar" nas solicitações ao servidor. Esse cabeçalho é necessário para informar ao servidor em que formato o cliente espera receber uma resposta. Vários formatos são fornecidos em uma 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:
Por exemplo, uma solicitação pode ter um cabeçalho como este:
Accept:application/json
Esse cabeçalho informa ao servidor que o cliente espera receber uma resposta no formato JSON.
Corpo da solicitação
Esta é a mensagem enviada pelo cliente ao servidor. Se a solicitação tem um corpo ou não, depende do tipo de solicitação HTTP. Por exemplo, as solicitações GET e DELETE geralmente não contêm nenhum corpo de solicitação. Mas as solicitações PUT e POST podem - depende apenas da finalidade da solicitação. Afinal, para receber e/ou deletar dados por meio de um ID (que é passado na URL), não é necessário enviar dados adicionais para o servidor. Mas para criar um novo recurso (por meio de uma solicitação POST), você precisa enviar o recurso. O mesmo é verdadeiro para modificar um recurso existente. No REST, o corpo da solicitação geralmente é enviado no formato XML ou JSON. O formato JSON é o mais comum. Suponha que queremos enviar uma solicitação ao servidor para criar um novo recurso. Se você não esqueceu, consideramos o exemplo de um aplicativo que gerencia pedidos de clientes. Digamos que queremos criar um novo cliente. No nosso caso, armazenamos as seguintes informações do cliente: Nome, e-mail, número de telefone. Em seguida, o corpo da solicitação pode ser o seguinte JSON:
Edite o número do cliente 1 da seguinte forma:
Nome — Ben
E-mail — bigben@jr.com
Número de telefone — +86 (868) 686-8686
DELETE /customers/12/orders/6
Excluir do sistema o pedido nº 6 feito pelo cliente nº 12
Respostas
Vamos dizer algumas palavras sobre as respostas do servidor. Uma resposta geralmente consiste nas seguintes partes:
Código de resposta
cabeçalhos
corpo da 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 em respostas e solicitações. Acho que também está tudo claro em relação ao corpo da solicitação. O corpo geralmente retorna informações solicitadas pelo cliente. As informações retornadas em resposta a solicitações GET também podem estar no formato JSON. Mas a última parte é um pouco mais interessante.
códigos de resposta HTTP
Vamos considerar os códigos de resposta HTTP com mais detalhes. Um código de status HTTP faz parte da primeira linha de uma resposta do servidor às solicitações feitas por meio do protocolo HTTP. É um número inteiro composto por três dígitos decimais. O primeiro dígito indica a classe do código de status de resposta. O código de resposta geralmente é seguido por uma frase explicativa em inglês, separada por um espaço. Esta frase é uma razão legível por humanos para a resposta. Exemplos:
201 criado
401 não autorizado
507 Armazenamento Insuficiente
O código de resposta informa ao cliente o resultado da solicitação e permite que ele determine quais ações tomar em seguida. Os códigos de resposta são divididos em várias classes ou grupos:
1XX — Informativo
2XX — Esses códigos indicam que a solicitação do cliente foi recebida e processada com sucesso
3XX — Esses códigos informam ao cliente que uma solicitação adicional, geralmente para um URI diferente, deve ser feita para concluir a operação com sucesso
4XX — Erro do cliente. Esses códigos podem resultar de uma solicitação composta incorretamente. Outro exemplo é o conhecido código "404 Not Found", que pode ocorrer quando um cliente solicita um recurso inexistente
5XX — Erro do servidor. Esses códigos são devolvidos ao cliente caso o servidor seja o responsável pela falha da operação
Para garantir que tudo esteja claro, analisaremos a comunicação cliente-servidor usando um aplicativo RESTful como exemplo. Suponha que estejamos desenvolvendo um aplicativo da Web que armazene informações sobre clientes e seus pedidos. Em outras palavras, nosso sistema é capaz de realizar operações em determinadas entidades: criá-las, editá-las, excluí-las e exibir informações sobre elas. Essas entidades serão:
