REST API: Conceito e fundamentos

O que é REST API?

REST (Representational State Transfer - Transferência Representacional de Estado) criada no ano 2000 por Roy Fielding.

Arquitetura que padroniza formas para criação de webservices, permitindo criação de serviços e integrações que utilizam HTTP como forma de comunicação.

Arquitetura REST

A análise necessária para utilização desta arquitetura deve considerar às seis regras do padrão e seus impactos nos elementos do sistema.

Regras:

1) Client-Server

Separação das responsabilidades entre Cliente (Consumidor de Serviço) e Servidor (Provedor do Serviço).

Simplifica os componentes do servidor melhorando a escalabilidade da aplicação.

Permite que os componentes evoluam de forma independente.

2) Stateless

Toda comunicação com o servidor deve ser feita de forma independente contendo todas as informações necessárias para concluir uma determinada operação.

• Vantagens:

  • Melhora a visibilidade da requisição, pois o servidor só precisa analisar a solicitação recebida para determinar a natureza dela.
  • É resiliente, se todas as informações exigidas pelo servidor estiverem em apenas uma solicitação, ele pode se recuperar mais facilmente de uma falha específica.
  • Melhora a escalabilidade, pois não é necessário manter recursos em memória e/ou componentes complexos compartilhados, porque cada requisito é independente.

• Desvantagens:

  • As requisições são sempre enviadas por completo, a quantidade de informações de tráfego aumenta porque não há contexto onde as informações serão compartilhadas entre cliente e servidor.
  • As informações da sessão são mantidas no cliente, o servidor é responsável por garantir que estejam sempre consistentes.

3) Cache

O cache ajuda a melhorar o desempenho, a escalabilidade e a eficiência, reduzindo o tempo médio de resposta em comparação com uma série de interações do cliente-servidor. 

Para otimizar o tráfego de informações, os sinais são adicionados à criação  do Client-Cache-Stateless. 

Essa sinalização indica que os dados contidos na resposta de solicitação podem ou não podem ser armazenados localmente para reutilização.

• Vantagens:

  • Se torna mais eficiente à medida que elimina interações desnecessárias. 
  • Melhora a escalabilidade e a remoção de latência entre os requisitos de determinadas ordens. 
  • Melhora o desempenho aparente do usuário. 

• Desvantagens:

  • O usuário pode usar informações que não são mais válidas e/ou completas.

4) Interface Uniforme

As principais características que distinguem o estilo arquitetural REST é uma interface uniforme entre os componentes do cliente e do servidor.
 
Como o cliente e o servidor compartilha essa interface, você precisa de um "contrato" definido para comunicação entre os lados. 

Há quatro princípios que devem ser seguidos para obter uma interface uniforme: Identificação dos Recursos, Representação dos Recursos, Mensagens Auto-Descritivas e Hypermedia (HATEOAS).

• Desvantagens:

  • É muito eficiente para transferir dados pequenos, otimizados para uso comum na Web, mas isso pode levar a implementações não eficientes para outras formas de interação.
  • Não é exatamente eficiente porque as informações transferidas estão disponíveis em um formato padronizado e não na forma de uma necessidade específica para a aplicação.

5) Sistema em camadas

Arquitetura deve ser construída em camadas gerenciadas de forma independente para que as mudanças não impactem nas demais.

Recomendado que o cliente nunca conecte diretamente no servidor de aplicação e que uma camada de balanceamento de carga seja adicionada entre cliente-servidor.

• Vantagens:

  • Arquitetura menos complexa e propícia a mudanças.

• Desvantagens:

  • Adiciona latência e sobrecarga durante o processamento de informações, mas esses pontos podem ser equilibrados com a criação de caches de fronteira entre camadas.

6) Código sob demanda

Permite a expansão das funções do cliente através do download e execução de extensões no formato de aplicativos ou scripts.

Simplifica a execução do cliente, porque não precisa ter todas as funções previamente implementadas.

É uma regra complexa a ser realizada porque você precisa conhecer todos os seus clientes.

Métodos HTTP

GET: Solicita a representação de um recurso.

HEAD: Retorna somente os cabeçalhos de uma resposta.

POST: Cria um recurso.

PUT: Se o recurso existe atualiza, caso não exista ele cria.

DELETE: Exclui um recurso.

CONNECT: Converte a requisição de conexão para um túnel TCP/IP transparente, geralmente para facilitar a comunicação criptografada com SSL (HTTPS) através de um proxy HTTP não criptografado.

OPTIONS: Retorna as opções de comunicação com o recurso de destino.

TRACE: Retorna a mesma solicitação que é enviada para ver se houve alterações e/ou adições feitas por servidores intermediários.

PATCH: Modifica parcialmente um recurso.

Terminologia REST:

1. Recurso (resource): conceitualmente falando, o alvo da interação desejada.

2. Identificador de recurso (Resource identifier): URL ou URN do recurso. Algo que seja único e o identifique.

3. Coleções (collections): Agrupamentos de recursos. (Exemplo: Cachorro é um item da Coleção de animais).

4. Representação (representation): Como o recurso é representado – Documento HTML, JSON, imagem (png, jpg, etc).

5. Metadata da Representação (representation metadata): tipo de midia, data da última modificação (last-modified-time).

6. Metadata do Recurso (resource metadata): link da fonte, alternativas e variações para aquele recurso, caso exista.

7. Informações de Controle (control data): cache-control, if-modified-since

Códigos de respostas HTTP

Os códigos de status das respostas HTTP indicam se uma requisição HTTP foi corretamente concluída. As respostas são agrupadas em cinco classes:

1. Respostas de informação (100-199),
2. Respostas de sucesso (200-299),
3. Redirecionamentos (300-399)
4. Erros do cliente (400-499)
5. Erros do servidor (500-599).

Respostas informativas

Código	Status	Tradução Status	Resposta
100	Continue	Continuar	Indica que tudo ocorreu bem até agora e que o cliente deve continuar com a requisição ou ignorar se já concluiu o que gostaria.
101	Switching Protocols	Mudando Protocolos	Esse código é enviado em resposta a um cabeçalho de solicitação Upgrade (en-US) pelo cliente, e indica o protocolo a que o servidor está alternando.
102	Processing	Processando	O servidor recebeu e está processando a requisição, mas nenhuma resposta está disponível ainda.
103	Early Hints	Dicas iniciais	Este código tem principalmente o objetivo de ser utilizado com o cabeçalho Link, indicando que o agente deve iniciar a pré-carregar recursos enquanto o servidor prepara uma resposta.

Respostas de sucesso

Código	Status	Tradução Status	Resposta
200	Ok	Ok	Requisição bem sucedida
201	Created	Criado	A requisição foi bem sucedida e um novo recurso foi criado como resultado.
202	Accepted	Aceitaram	A requisição foi recebida mas nenhuma ação foi tomada sobre ela.
203	Non-Authoritative Information	Não autorizado	O conjunto de meta-informações retornadas não é o conjunto exato disponível no servidor de origem, mas coletado de uma cópia local ou de terceiros.
204	No Content	Nenhum Conteúdo	Não há conteúdo para enviar para esta solicitação, mas os cabeçalhos podem ser úteis. O user-agent pode atualizar seus cabeçalhos em cache para este recurso com os novos.
205	Reset Content	Resetar Conteúdo	Esta requisição é enviada após realizanda a solicitação para informar ao user agent redefinir a visualização do documento que enviou essa solicitação.
206	Partial Content	Conteúdo Parcial	Esta resposta é usada por causa do cabeçalho de intervalo enviado pelo cliente para separar o download em vários fluxos.
207	Multi-Status	Multi-Status	Uma resposta Multi-Status transmite informações sobre vários recursos em situações em que vários códigos de status podem ser apropriados.
208	Multi-Status	Multi-Status	Usado dentro de um elemento de resposta dav:propstat para evitar enumerar os membros internos de várias ligações à mesma coleção repetidamente.
226	IM Used	Estou acostumado	O servidor cumpriu uma solicitação GET para o recurso e a resposta é uma representação do resultado de uma ou mais manipulações de instância aplicadas à instância atual.

Mensagens de redirecionamento

Código	Status	Tradução Status	Resposta
300	Multiple Choices	Múltipla Escolha	A requisição tem mais de uma resposta possível. User-agent ou o user deve escolher uma delas. Não há maneira padrão para escolher uma das respostas.
301	Moved Permanently	Movido Permanentemente	A URI do recurso requerido mudou. Provavelmente, a nova URI será especificada na resposta.
302	Found	Encontrado	A URI do recurso requerido foi mudada temporariamente. Novas mudanças na URI poderão ser feitas no futuro. Portanto, a mesma URI deve ser usada pelo cliente em requisições futuras.
303	See Other	Veja outro	O servidor manda essa resposta para instruir ao cliente buscar o recurso requisitado em outra URI com uma requisição GET.
304	Not Modified	Não modificado	Usada para questões de cache. Diz ao cliente que a resposta não foi modificada. Portanto, o cliente pode usar a mesma versão em cache da resposta.
305	Use Proxy	Use Proxy	Foi definida em uma versão anterior da especificação HTTP para indicar que uma resposta deve ser acessada por um proxy. Foi depreciada por questões de segurança em respeito a configuração em banda de um proxy.
306	Proxy Switch	Proxy Trocado	Esse código de resposta não é mais utilizado, encontra-se reservado. Foi usado numa versão anterior da especificação HTTP 1.1.
307	Temporary Redirect	Redirecionamento temporário	O servidor mandou essa resposta direcionando o cliente a buscar o recurso requisitado em outra URI com o mesmo método que foi utilizado na requisição original.
308	Permanent Redirect	Redirecionamento Permanente	O recurso agora está permanentemente localizado em outra URI, especificada pelo cabeçalho de resposta Location.

Respostas de erro do Cliente

Código	Status	Tradução Status	Resposta
400	Bad Request	Solicitação Inválida	o servidor não entendeu a requisição pois está com uma sintaxe inválida.
401	Unauthorized	Não autorizado	O cliente deve se autenticar para obter a resposta solicitada.
402	Payment Required	Pagamento necessário	O processo não pôde ser realizado em função de um pagamento não realizado
403	Forbidden	Proibido	O cliente não tem direitos de acesso ao conteúdo portanto o servidor está rejeitando dar a resposta.
404	Not Found	Não encontrado	O servidor não pode encontrar o recurso solicitado.
405	Method Not Allowed	Método não permitido	O método de solicitação é conhecido pelo servidor, mas foi desativado e não pode ser usado.
406	Not Acceptable	Não aceito	o servidor da Web após realizar a negociação de conteúdo orientada pelo servidor, não encontra nenhum conteúdo seguindo os critérios fornecidos pelo agente do usuário.
407	Proxy Authentication Required	Autenticação de Proxy Necessária	O cliente deve se autenticar por meio de um proxy para obter a resposta solicitada.
408	Request Time-out	Tempo de solicitação esgotado	o servidor gostaria de derrubar esta conexão em desuso.
409	Conflict	Conflito	Esta resposta será enviada quando uma requisição conflitar com o estado atual do servidor.
410	Gone	Perdido	O conteúdo requisitado foi permanentemente deletado do servidor, sem nenhum endereço de redirecionamento.
411	Length Required	Duração necessária	O servidor rejeitou a requisição porque o campo Content-Length do cabeçalho não está definido e o servidor o requer.
412	Precondition Failed	Falha de pré-condição	O cliente indicou nos seus cabeçalhos pré-condições que o servidor não atende.
413	Request Entity Too Large	Solicitação da entidade muito extensa	A entidade requisição é maior do que os limites definidos pelo servidor; o servidor pode fechar a conexão ou retornar um campo de cabeçalho Retry-After.
414	Request-URL Too Large	Solicitação de URL muito Longa	A URI requisitada pelo cliente é maior do que o servidor aceita para interpretar.
415	Unsupported Media Type	Tipo de mídia não suportado	O formato de mídia dos dados requisitados não é suportado pelo servidor, então o servidor rejeita a requisição.
416	Request Range Not Satisfiable	Solicitação de faixa não satisfatória	O trecho especificado pelo campo Range do cabeçalho na requisição não pode ser preenchido; é possível que o trecho esteja fora do tamanho dos dados da URI alvo.
417	Expectation Failed	Falha na expectativa	Este código de resposta significa que a expectativa indicada pelo campo Expect do cabeçalho da requisição não pode ser satisfeita pelo servidor.
418	I'm a teapot	Eu sou um bule de chá	O servidor recusa a tentativa de coar café num bule de chá.
421	Misdirected Request	Pedido mal direcionado	A requisição foi direcionada a um servidor inapto a produzir a resposta. Pode ser enviado por um servidor que não está configurado para produzir respostas para a combinação de esquema ("scheme") e autoridade inclusas na URI da requisição.
422	Unprocessable Entity	Entidade não processável	A requisição está bem formada mas inabilitada para ser seguida devido a erros semânticos.
423	Locked	Trancado	O recurso sendo acessado está travado.
424	Failed Dependency	Dependência falhada	A requisição falhou devido a falha em requisição prévia.
425	Too Early	Muito cedo	Indica que o servidor não está disposto a arriscar processar uma requisição que pode ser refeita.
426	Upgrade Required	Requer atualização	O servidor se recusa a executar a requisição usando o protocolo corrente mas estará pronto a fazê-lo após o cliente atualizar para um protocolo diferente.
428	Precondition Required	Pré-condição necessária	O servidor de origem requer que a resposta seja condicional. Feito para prevenir o problema da 'atualização perdida', onde um cliente pega o estado de um recurso (GET) , modifica-o, e o põe de volta no servidor (PUT), enquanto um terceiro modificou o estado no servidor, levando a um conflito.
429	Too Many Requests	Muitos pedidos	O usuário enviou muitas requisições num dado tempo ("limitação de frequência").
431	Request Header Fields Too Large	Solicitar campos de cabeçalho muito grandes	O servidor não quer processar a requisição porque os campos de cabeçalho são muito grandes. A requisição PODE ser submetida novamente depois de reduzir o tamanho dos campos de cabeçalho.
451	Unavailable For Legal Reasons	Indisponível por motivos legais	O usuário requisitou um recurso ilegal, tal como uma página censurada por um governo.

Respostas de erro do Servidor

Código	Status	Tradução Status	Resposta
500	Internal Server Error	Erro do Servidor Interno	O servidor encontrou uma situação com a qual não sabe lidar.
501	Not Implemented	Não implementado	O método da requisição não é suportado pelo servidor e não pode ser manipulado.
502	Bad Gateway	Porta de entrada ruim	O servidor, ao trabalhar como um gateway a fim de obter uma resposta necessária para manipular a requisição, obteve uma resposta inválida.
503	Service Unavailable	Serviço Indisponível	O servidor não está pronto para manipular a requisição. Causas comuns são um servidor em manutenção ou sobrecarregado.
504	Gateway Time-out	Tempo limite da Porta de Entrada	o servidor está atuando como um gateway e não obtém uma resposta a tempo.
505	HTTP Version Not Supported	Versão HTTP não suportada	A versão HTTP usada na requisição não é suportada pelo servidor.
506	Variant Also Negotiates	A variante também negocia	O servidor tem um erro de configuração interno: a negociação transparente de conteúdo para a requisição resulta em uma referência circular.
507	Insufficient Storage	Armazenamento Insuficiente	O servidor tem um erro interno de configuração: o recurso variante escolhido está configurado para entrar em negociação transparente de conteúdo com ele mesmo, e portanto não é uma ponta válida no processo de negociação.
508	Loop Detected	Loop detectado	O servidor detectou um looping infinito ao processar a requisição.
510	Not Extended	Não estendida	Exigem-se extenções posteriores à requisição para o servidor atendê-la.
511	Network Authentication Required	Autenticação de rede necessária	Cliente precisa se autenticar para ganhar acesso à rede.