REST API: Conceito e fundamentos
Published: 2021-03-19 14:15:01

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.