O básico de APIs RESTful parte 1 - definições e restrições
Tags: restful, api, backend, webdev
Published: 2020-12-30 19:42:22

Estou escrevendo esta série enquanto me aprofundo em desenvolvimento de APIs.
Já trabalho com APIs faz quase dois anos mas, sinto que muita coisa não ficou muito consolidada na minha mente. Portanto, vou compartilhando aqui para me ajudar a fixar - e porque talvez possa ser útil para alguém.

Adianto que não me responsabilizo por boa didática. Provavelmente vocês vão encontrar texto muito mais didáticos ou até mesmo, vão ter sugestões de abordagens melhores para o tema. Neste caso, **encorajo vocês a escreverem seus artigos que eu os divulgarei com muito prazer <3**. 
O meu texto vai ser isso aqui mesmo. 
No mais, fico a disposição nos comentários.

#API RESTful - parte 1

###Em resumo, como uma API RESTful funciona?
O cliente faz a solicitação, a API REST recebe a solicitação, coleta e analisa os dados e retorna esses dados e o cabeçalho de resposta ao cliente.

###O que significa API REST?
REST e API são acrônimos para Representational State Transfer e Application Programming Interface.

### O que é REST?
REST refere-se a um grupo de restrições de design de arquitetura de software que geram sistemas eficientes, confiáveis ​​e escaláveis. 

A Transferência de Estado Representacional é uma descrição literal do que acontece: transição entre representações de estados e essas representações sendo transferidas entre o aplicativo e o servidor.

Todas essas idas e vindas são controladas por meio de uma interface de programação de aplicativo - a API.

Lembrando que este estado representacional é transferido como um objeto de dados, não como um novo conjunto de arquivos.

###O que é API?

Conjunto de recursos e regras que existem dentro de um programa de software, permitindo a interação entre o software e outros itens, como outro software ou hardware.

No contexto das APIs REST, a API é a coleção de ferramentas usadas para acessar e trabalhar com recursos REST por meio de seus verbos, como GET, PULL, PUT e DELETE.

###Analogia para fixar:
Você pode pensar no recurso REST como uma bibliotecária e a API como a forma de solicitar um livro (o que você precisa passar para a bibliotecária te entregar aquilo que necessita? O que precisa: colocar um novo livro na biblioteca? Solicitar os mais recentes? Tirar um livro permanentemente?).

##Que mais preciso saber?

###URI

O URI - Identificador de Recurso Universal - é descrito como uma "seqüência compacta de caracteres", é o método mais genérico para nomear e localizar um recurso da web.

###URL

O URL - Universal Resource Locator - não apenas identifica um recurso, mas também explica como acessar esse recurso, fornecendo um método explícito como HTTP ou FTP.

**Todos os URLs são URIs, mas nem todos os URIs são URLs.**

###URN
O URN - Universal Resource Name - se refere a ambos os URIs e a qualquer outro com as propriedades de um nome.

##Analogia:
A diferença entre um URN e um URL é dizer que o URN é um identificador de nome exclusivo, como o nome completo de uma pessoa, enquanto a URL fornece a localização física real.

###Para lembrar:
**URL também pode ser um URN e ambos são URIs.**

##As 6 Restrições em REST

###Arquitetura cliente-servidor
Garante a separação adequada entre o conteúdo e sua apresentação e interação.

O cliente gerencia as questões da interface do usuário, enquanto o servidor gerencia as questões de armazenamento de dados. 

###Não guardar estados

Nenhum contexto ou informação do cliente (estado) pode ser armazenado no servidor entre as solicitações.

Se o estado de sessão do cliente for relevante, ele deve ser enviado junto com uma solicitação.

Se o servidor precisar armazenar esse estado, ele deve passá-lo para um banco de dados ou serviço semelhante por um tempo **específico.** 

O "estado" é o que determina 'onde' o usuário está no processo de conclusão de uma tarefa(1).

###Capacidade de armazenamento em cache
Armazenar em cache respostas que não mudarão ou provavelmente não sofrerão alterações, as alteradas raramente ou periodicamente por períodos de tempo razoáveis ​​e bloquear o cache para respostas em constante mudança.

###Sistema em camadas
O sistema deve ser projetado de forma que o cliente não saiba e não se importe se está conectado diretamente ao servidor ou a um intermediário.

###Código sob demanda
Os servidores têm permissão para transferir código executável na forma de JavaScript do lado do cliente e para transferencia de componentes compilados, com o objetivo de estender e personalizar a funcionalidade. 

###Interface uniforme
Se divide em mais quatro restrições, portanto, não é realmente uma única restrição, mas apenas mais quatro restrições:

- O que REST retorna é uma representação do recurso, que pode ter um formato diferente do recurso no servidor. Exemplo: Dados armazenados como uma tabela no banco, mas representação de retorno pode ser JSON, XML ou HTML;

- O cliente com o nível de acesso correto pode controlar o que está armazenado no servidor;

- Cada representação deve descrever seu próprio formato de dados;

- O serviço REST descreve seu próprio uso com cada recurso retornado, por meio dos hiperlinks fornecidos.

A API só é REST se atender a estas restrições, lembrando que a restrição de código por demanda é considerada por alguns autores como opcional.

Referências:
(1)[Hypermedia in RESTful applications - Mark Baker, 2008]
(https://www.infoq.com/articles/mark-baker-hypermedia/)

Outras referências:

[Curso online "Learning REST APIs" - Morten Rand-Hendriksen](https://www.linkedin.com/learning/learning-rest-apis/welcome)

[Livro "Essentials of RESTful Web Services,Java, Spring Boot, Spring MVC and JPA: Top 100 real life project scenarios and tips" - Pagebuzzes Publications](https://www.amazon.com.br/Essentials-RESTful-Services-Java-Spring-ebook/dp/B08Q8QY4R9/ref=sr_1_1?__mk_pt_BR=ÅMÅŽÕÑ&dchild=1&keywords=Essentials+of+RESTful+Web+Services%2CJava%2C+Spring+Boot%2C+Spring+MVC+and+JPA%3A+Top+100+real+life+project+scenarios+and+tips&qid=1609756842&s=digital-text&sr=1-1)