O que diabos é uma "API"?! E pior ainda uma "API REST(ful)"?

 O que é uma API de REST?

Uma API, ou interface de programação aplicativos, é um conjunto de regras que definem como aplicativos ou dispositivos podem se conectar e se comunicar uns com os outros. Uma API de REST é uma API que se adéqua aos princípios de design do REST ou o estilo de arquitetura do Representational State Transfer.  Por esta razão, as APIs de REST são muitas vezes chamadas de APIs de RESTful.

Definido pela primeira em 2000 pelo cientista de computação Dr. Roy Fielding em sua dissertação de doutorado, o REST proporciona um nível relativamente alto de flexibilidade e liberdade para desenvolvedores. Essa flexibilidade é apenas uma razão pela qual as APIs de REST surgiram como um método comum para conectar componentes e aplicativos em uma arquitetura de microsserviços.

Princípios de design REST

Basicamente, uma API é um mecanismo que permite que um aplicativo ou serviço acesse um recurso dentro de outro aplicativo ou serviço. O aplicativo ou serviço que está realizando o acesso é chamado de cliente, e o aplicativo ou serviço contendo o recurso é chamado de servidor.

Algumas APIs, como SOAP ou XML-RPC, impõe um framework restrito para os desenvolvedores. Porém, as APIs de REST podem ser desenvolvidas usando praticamente qualquer linguagem de programação e oferecem suporte a uma variedade de formatos de dados. O único requisito é que eles devem alinhar aos seis princípios de design de REST a seguir, conhecidos como restrições de arquitetura:

1. Interface uniforme. Todas as solicitações da API para o mesmo recurso devem ser iguais, não importa a origem da solicitação. A API de REST deve garantir que a mesma parte dos dados dados, como o nome ou endereço de e-mail de um usuário, pertença a apenas um identificador de recurso uniforme (URI). Os recursos não devem ser muito grandes mas devem conter todas as informações que o cliente pode precisar.
2. Desacoplamento do cliente-servidor. No projeto da API  de REST, os aplicativos cliente e servidor devem ser completamente independentes um do outro. A única informação que o aplicativo cliente deve receber é o URI do recurso solicitado. Ele não pode interagir com o aplicativo do servidor de qualquer outra forma. Da mesma forma, um aplicativo do servidor não deve modificar o aplicativo cliente, exceto para transferi-los aos dados solicitados via HTTP.
3. Sem estado definido. As APIs de REST não possuem estado definido, o que significa que cada solicitação precisa incluir todas as informações necessárias para processá-lo. Em outras palavras, as APIs de REST não requerem nenhuma sessão do lado do servidor. Os aplicativos do servidor não tem permissão para armazenar nenhum dado relacionado a uma solicitação de cliente.
4. Capacidade de armazenamento em cache. Quando possível, os recursos devem ser armazenados em cache pelo cliente ou servidor. As respostas do servidor também precisam conter informações sobre as permissões de cache do recurso fornecido. O objetivo é melhorar o desempenho do cliente, além de aumentar a escalabilidade do servidor.
5. Arquitetura de sistema em camadas. Em APIs de REST, as chamadas e respostas passam por diferentes camadas. De maneira geral, não assuma que os aplicativos cliente e servidor se conectem diretamente um ao outro. Pode haver uma série de intermediários diferentes no loop de comunicação. As APIs de REST precisam ser projetadas para que nem o cliente e nem o servidor possam dizer se ele se comunica com o aplicativo final ou um intermediário.
6. Código sob demanda (opcional). As APIs de REST geralmente enviam recursos estáticos, mas em certos casos, as respostas também podem conter código executável (como applets Java). Nestes casos, o código deve ser executado somente sob demanda.

Como as APIs de REST funcionam

As APIs de REST se comunicam via solicitações de HTTP para executar funções padrão do banco de dados como criar, ler, atualizar e excluir registros (também conhecidos como CRUD) em um recurso. Por exemplo, uma API de REST usaria uma solicitação GET para recuperar um registro, uma solicitação POST para criar um registro, uma solicitação PUT para atualizar um registro e uma solicitação DELETE para excluir um registro. Todos os métodos HTTP podem ser usados em chamadas da API. Uma API de REST bem projetada é semelhante a um website em execução em um navegador da web com funcionalidade HTTP integrada.

O estado de um recurso em qualquer horário específico, ou registro de data e hora, é conhecido como representação de recursos. Estas informações podem ser entregues a um cliente em praticamente qualquer formato, incluindo JavaScript Object Notation (JSON), HTML, XLT, Python, PHP ou texto simples. O JSON é bastante usado, porque é legível tanto por humanos quanto por máquinas, além de ser uma programação de linguagem independente.

Os cabeçalhos e parâmetros de solicitação também são importantes em chamadas de API de REST, porque incluem informações importantes do identificador como metadados, autorizações, identificadores de recursos uniformes (URIs), armazenamento em cache, cookies e mais. Os cabeçalhos de solicitação e cabeçalhos de resposta, juntamente aos códigos de status HTTP convencionais, são usados dentro de APIs de REST bem projetadas.

Melhores práticas da API de REST

Embora a flexibilidade seja uma grande vantagem do projeto de API de REST,  essa mesma flexibilidade facilita a criação de uma API que está com falhas ou baixo desempenho. Por esta razão, desenvolvedores profissionais compartilham melhores práticas em especificações da API de REST.

A OpenAPI Specification (OAS) estabelece uma interface para descrever uma API de forma que permita que um desenvolvedor ou aplicativo o descubram e entendam completamente seus parâmetros e recursos, como terminais disponíveis, operações permitidas em cada terminal, parâmetros de operações, métodos de autenticação e outras informações. A versão mais recente, OAS3 (link externo à ibm.com), inclui ferramentas práticas, como o OpenAPI Generator, para geração de clientes API e stubs de servidor em diferentes linguagens de programação.

Proteger uma API de REST também começa com a adoção das melhores práticas do mercado, como usar algoritmos de hashing para segurança de senha e HTTPS para transmissão de dados segura. Uma estrutura para autorização, como o OAuth 2.0  (link externo à ibm.com), pode ajudar a limitar os privilégios de aplicativos de terceiros. Com um registro de data e hora no cabeçalho HTTP, uma API também pode rejeitar qualquer solicitação que chegue após um determinado período. A validação de parâmetros e JSON Web Tokens são outras formas de garantir que apenas clientes autorizados possam acessar a API.

• API significa Application Programming Interface 
• No contexto de APIs, a palavra Aplicação refere-se a qualquer software com uma função distinta. 
• A Interface pode ser pensada como um contrato de serviço entre duas aplicações. 
• Esse contrato define como as duas se comunicam usando solicitações e respostas.
• A documentação de suas respectivas APIs contém informações sobre como os desenvolvedores devem estruturar essas solicitações e respostas.
• A arquitetura da API geralmente é explicada em termos de cliente e servidor. 
• A aplicação que envia a solicitação é chamada de cliente e a aplicação que envia a resposta é chamada de servidor. 

• APIs SOAP: Cliente e servidor trocam mensagens usando XML. Esta é uma API menos flexível que era mais popular.
• APIs RPC: O cliente conclui uma função (ou um procedimento) no servidor e o servidor envia a saída de volta ao cliente.
• APIs WebSocket: O servidor pode enviar mensagens de retorno de chamada a clientes conectados, tornando-o mais eficiente que a API REST.

• APIs REST: O cliente envia solicitações ao servidor como dados. O servidor usa essa entrada do cliente para iniciar funções internas e retorna os dados de saída ao cliente.
• REST significa Transferência Representacional de Estado. 
• Clientes e servidores trocam dados usando HTTP.
• O HTTP permite criar, atualizar, pesquisar, executar e remover operações, atuando sob determinados recursos. 
• A principal característica da API REST é a ausência de estado.

Vamos agora conhecer as restrições de arquitetura que caracterizam uma API RESTful:

• Arquitetura cliente-servidor: indica uma arquitetura baseada em clientes, servidores e recursos, em que as solicitações são feitas via protocolo HTTP. Essa condição está ligada à independência entre o cliente e o servidor. Ou seja, mudanças feitas pelo usuário na aplicação em seu dispositivo não devem afetar o servidor e sua estrutura de dados. De mesmo modo, alterações feitas pelos desenvolvedores nos bancos de dados da aplicação não devem instantaneamente impactar o dispositivo do usuário.
• Comunicação stateless: a comunicação feita entre cliente e servidor não deve armazenar nenhuma informação entre as solicitações. Em uma REST API, cada solicitação contém todos os dados necessários para que seja atendida, não dependendo de informações já armazenadas em outras sessões.
• Cache: uma API REST deve ser desenvolvida de modo que consiga armazenar dados em cache. Quando uma informação fica armazenada em cache, as solicitações e respostas entre cliente e servidor são otimizadas.
• Interface uniforme: a interface uniforme é o que permite o desenvolvimento independente da aplicação entre usuário e servidor. Uma REST API deve conter uma interface uniforme pois ela oferece uma comunicação padronizada entre o usuário e o software. A manipulação de recursos através de representações (como JSON ou XML), é uma das condições para o desenvolvimento de uma interface uniforme.
• Sistema de camadas: cada camada do sistema deve possuir uma funcionalidade específica (como segurança ou carregamento). Assim, cada camada é responsável por uma etapa diferente dos processos de requisição de usuário e de resposta do servidor. Essas camadas são ordenadas hierarquicamente mas, apesar de serem separadas, todas interagem entre si.

Como Funcionam as APIs RESTful

Uma API RESTful funciona através da manipulação de recursos e representações. Essas representações são trocadas entre os usuários e o servidor através de uma interface padronizada e de um protocolo de comunicação específico — geralmente o HTTP.

Assim, quando um usuário deseja usar uma funcionalidade da aplicação, seu dispositivo envia uma solicitação via HTTP ao servidor. O servidor localiza o recurso e comunica a representação do estado dele na resposta ao usuário através do mesmo protocolo. E são essas representações que podem ser feitas em diversos formatos.

(Fonte: Seobility/Reprodução)

As solicitações da aplicação requerem a execução de alguma função padrão no banco de dados do sistema. Por exemplo, a API RESTful envia ao servidor, via HTTP, uma requisição para executar uma função básica, como deletar o usuário “Pedro” da lista de usuários. A solicitação enviada nesse exemplo, seria a seguinte:

DELETE http://www.meusite.com.br/usuarios/pedro

As operações utilizadas para acessar os recursos são padronizadas e bem definidas, além do comando DELETE, existem outros, como http GET e POST que solicitam, respectivamente, a recuperação e a criação de um recurso ou usuário.

Usos de uma API REST

Uma API RESTful oferece altos níveis de liberdade e flexibilidade para os desenvolvedores. Seu uso é benéfico principalmente em aplicações em nuvem (servidores cloud).

Os princípios REST possibilitam que as representações enviadas pelo servidor estejam em diversos formatos (como JSON, XML, Python, etc.). Com isso, eles permitem a criação de uma API que responde às necessidades tanto da aplicação quanto dos diversos usuários.

Além da flexibilidade, uma API RESTful tende a utilizar menos largura de banda, tornando o uso da internet mais eficiente.

Uma das restrições listadas na arquitetura REST é a comunicação stateless. Ela traz benefícios importantes para as aplicações Cloud, pois permite que componentes sejam facilmente lançados novamente caso algo falhe, além de facilitar a adaptação quando há flutuação de tráfego.

Cada solicitação possui todas as informações necessárias para que o servidor responda com as representações solicitadas. Isso torna a API RESTful ideal para serviços web, especialmente aqueles baseados em nuvem. Ela se torna a escolha mais lógica pois permite a conexão, a gestão e a interação dos usuários com os servidores Cloud de forma padronizada, flexível e escalável.

Deste modo, o padrão REST é o método de preferência na integração de aplicações e na conexão de componentes de softwares. Grandes sites como Twitter, Amazon e Linkedin utilizam APIs do tipo RESTful. E a tendência é que a computação em nuvem confirme cada vez mais a arquitetura API REST como via de regra no desenvolvimento de aplicações no futuro.

Como Surgiu o REST
A arquitetura de sistema REST foi criada pelo cientista da computação Roy Fielding em 2000. Anteriormente ele já havia trabalhado na criação do protocolo HTTP e do URI — Identificador Uniforme de Recursos, um conjunto de elementos que identifica recursos nas aplicações web.
Buscando padronizar e organizar os protocolos de comunicação e desenvolvimento na internet, Fielding se uniu a um time de especialistas para desenvolver, durante 6 anos, as características da Representational State Transfer (REST), que foi definida em sua tese de PhD.

Diferença Entre REST e RESTful
Em termos de nomenclatura, é importante sabermos a diferença entre os conceitos de REST e RESTful.
Como já definimos anteriormente, REST é um conjunto de princípios e restrições de arquitetura de softwares.
Uma API RESTful é aquela que está em conformidade com os critérios estabelecidos pela Transferência de Estado Representacional (REST).
Assim, quando uma API é do tipo RESTful, significa que esse sistema consegue aplicar os princípios propostos por Roy Fielding em sua tese REST.

Conclusão
Quando você interage com uma aplicação na internet, é função da API ajudar a comunicar o que você deseja ao sistema, para que o servidor possa entender e realizar sua solicitação.

O estilo de arquitetura REST representa um conjunto específico de princípios que, se aplicados no desenvolvimento de uma aplicação web, caracterizam uma API RESTful.

Os critérios que devem ser cumpridos são:

• Sistema no formato cliente-servidor
• Comunicação stateless
• Capacidade de armazenar dados em cache
• Interface uniforme
• Sistema de camadas

Por indicar uma Transferência de Estado Representacional, a arquitetura REST possibilita o acesso, a organização e conexão dos usuários aos serviços da aplicação na internet, principalmente àqueles baseados na nuvem (servidores cloud).

As restrições listadas pelo estilo REST indicam benefícios importantes para o desenvolvimento de aplicações e sistemas. Afinal, elas resultam em maior flexibilidade, menor consumo de banda, mais segurança e padronização de protocolos. Assim, as tecnologias REST e RESTful tendem a crescer ainda mais no futuro, tornando-se os padrões mais populares para estas funções.

Fontes e referências:

• https://academiapme-my.sharepoint.com/:p:/g/personal/renato_dio_me/ERVAxF7Z_uBIoMMef0ns7EUB-pRDR2J0pSJ4PS29L27_2w?rtime=gQh_Sb4u3Eg
• https://www.hostinger.com.br/tutoriais/api-restful
• https://www.ibm.com/br-pt/topics/rest-apis