Desenvolvimento de APIs: 4 conceitos básicos que você precisa conhecer

APIs (Application Programming Interface) são interfaces de programação que funcionam como uma ponte, conectando dois sistemas distintos, possibilitando que se comuniquem.

Na prática, trata-se de um conjunto de rotinas e padrões que permitem que esses sistemas troquem informações entre si.

Com o surgimento de novos softwares a cada dia, o desenvolvimento de APIs tem sido uma habilidade cada vez mais requisitada no mercado de tecnologia.

Assim, se você quer se destacar neste cenário, é fundamental que entenda, em detalhes, como desenvolver  APIs e as boas práticas envolvidas na área.

Neste post, vamos nos aprofundar no assunto, entendendo como funciona o desenvolvimento de APIs REST, por meio de quatro conceitos básicos relacionados a essa atividade. Boa leitura!

O que é REST no desenvolvimento de APIs?

REST (Representational State Transfer) é um estilo arquitetural. Ou seja, define um conjunto de restrições e contratos arquiteturais. Assim, uma API que é aderente às restrições e contratos REST, é considerada RESTful, e é projetada para fazer um ótimo uso do protocolo HTTP.

Essa é uma grande vantagem desse estilo, uma vez que a infraestrutura utilizada para atender a esse protocolo, como servidores, caches e proxies, é largamente disponível. Inclusive, vale mencionar que o uso de REST é considerado uma das boas práticas no desenvolvimento de APIs.

O sucesso da Web — que é baseada no HTTP — é uma prova da longevidade e escalabilidade de arquiteturas neste formato. E o REST usa exatamente essas características, que funcionam tão bem na Web, para o desenvolvimento de APIs.

Mas, antes de entrar em detalhes sobre REST, é importante esclarecer alguns equívocos quanto a esse estilo arquitetural:

• REST não é um padrão;
• REST não é um protocolo;
• REST é um estilo arquitetural, constituído de algumas características baseadas no protocolo HTTP.

< Leia também: Conheça as 10 principais linguagens Front-End />

4 conceitos básicos no desenvolvimento de APIs REST

Conheça alguns dos principais conceitos que fazem parte da rotina de desenvolvimento de APIs do tipo REST:

1. Recurso

Assim como no HTTP, o conceito central do REST é o resource, que é uma abstração de um modelo de dados, o qual pode ser construído hierarquicamente, podendo conter sub-resources. Cada um desses elementos pode ser identificado por sua URI (Uniform Resource Identifier) única.

Um resource é basicamente uma estrutura de dados, que pode ser serializada para várias representações concretas, como JSON ou XML.

É importante saber que, para as rotinas de criar, recuperar, alterar e remover, um número de diferentes métodos é definido. Portanto, nem todos os resources suportam todos os métodos.

Resources são semelhantes a objetos da programação orientada a objetos (POO). Essa comparação se estende até ao que se refere à presença de campos de dados e métodos que manipulam esses campos.

Existe, portanto, uma diferença importante entre REST e POO: os métodos em REST são descritos como um conjunto de métodos HTTP (GET, PUT, POST, etc), enquanto que em POO, os métodos podem ser arbitrários.

Esse conjunto de métodos HTTP é a interface comum do resource (uniform resource interface). Por outro lado, os métodos HTTP especificam a interface comum, ou seja, nenhum outro método pode ser usado para manipular o resource.

Do mesmo modo, que nenhum outro método pode ser especificado nas requisições de API e no HTTP body, e o mesmo vale para o path base e para os parâmetros.

O termo API não é oficialmente definido em REST. Especificamos uma API como um resource-raíz , o qual pode conter outros sub-resources.

Qual a diferença entre APIs e resources?

Resources formam modelos de dados hierárquicos. Nessa hierarquia, o resource raíz é, de alguma forma, especial. Ele é chamado de API. Uma API pode conter vários sub resources, que são tipicamente usados juntos.

< Não sabe como apresentar o seu trabalho? Confira este post: Portfólio de desenvolvedor front-end: aprenda a criar o seu />

2. Representação

Dados concretos são servidos na forma de representações. Assim, podemos pensar na representação como um resource serializado.

Diferentes estruturas de codificação (ou tipos de mídia) podem ser usadas para essa serialização. Dessa forma, cada resource pode ser apresentado em um número de representações.

Qual a diferença entre resources e representações?

Resources são uma abstração do modelo de dados. Assim que o resource é retornado para o cliente, é necessário que seja serializado numa representação concreta.

Vale destacar que as regras para a criação dessas representações podem ser diferentes, produzindo XML ou JSON. Porém, todas as representações de um mesmo resource contém a mesma informação: a informação do resource.

< Leia também: Desenvolvedor full stack: o que faz e por que ter este profissional no time? />

3. Interface Comum (Uniform Resource Interface)

REST APIs geralmente executam operações CRUD (create, read, update, delete), que podem ser facilmente mapeadas em métodos HTTPs: criação pode ser desempenhado pelo POST, leitura pode ser desempenhado pelo GET , alteração pelo PUT e a exclusão pelo DELETE .

Esses métodos HTTPs constituem a interface comum ou Uniform Resource Interface, e são os mesmos para todos os resources.

Cada método HTTP tem uma proposta específica e também define um conjunto de características: os métodos HTTPs podem ser seguros e idempotente:

• Métodos idempotentes: podem ser executados repetidamente, sem alterar o resultado final. Ou seja, executando o método múltiplas vezes, têm-se o mesmo efeito, como se tivesse sido executado apenas uma vez;
• Métodos seguros: não têm efeitos colaterais. Logo, não mudam o estado de um resource e são read-only.

No desenvolvimento de APIs em REST, constrói-se o resource orientado à interface. Dessa forma, estruturas de dados são abstrações, e um resource é uma interface. Um pequeno conjunto fixo de operações (métodos HTTPs) são usados para operar sobre a interface do resource.

Por exemplo: para desenvolver um modelo de carrinho de compras para um e-commerce, podemos modelar apenas o resource shoppingcar, que é responsável por definir a interface. Vale dizer que é possível construí-lo sem especificar o uso dos métodos HTTPs.

Sabemos que REST é incompatível com os estilos baseados em procedimentos como SOAP e RPC. Dessa forma, quando definimos procedimentos orientados a interfaces, atividades ou operações, estamos apenas fazendo abstrações.

Voltando ao exemplo do carrinho para e-commerce, poderíamos modelar usando SOAP ou RPC: createShoppingCar(), updateShoppingCar(id, newItem), getShoppingCart(id) e deleteShoppingCart(id).

Também é importante notar que REST define um conjunto de restrições para o projeto de API. Assim, a maioria das restrições são, na verdade, restrições HTTPs, e REST leva essas restrições para as APIs.

O estilo REST assegura que APIs usem o HTTP corretamente. Porém, essas restrições limitam a liberdade de projeto. Então, nem todo projeto é permitido.

No entanto, usando o HTTP corretamente no desenvolvimento de APIs, você consegue as propriedades desejadas. Já REST, impõe as seguintes:

• uso das capacidades HTTP ao máximo;
• desenho dos resources (substantivos), não métodos e operações (verbos);
• uso do uniform interface definido pelos métodos HTTPs, que têm uma semântica bem definida;
• comunicação stateless entre cliente e servidor;
• uso de baixo acoplamento e independência dos requests;
• uso dos códigos de HTTPs de retorno;
• uso de media-types.

< Talvez você também se interesse por este post: Por que o desenvolvedor front-end é tão requisitado pelo mercado? />

4. Estado

Em sistemas distribuídos, a informação precisa ser preservada entre as chamadas. É esse movimento que chamamos de “estado”.

Uma vez que os sistemas distribuídos são formados por dois componentes: cliente e servidor, o estado pode ser preservado em qualquer um deles.

Um componente, que armazena a informação de estado entre as chamadas, é chamado de stateful. Já um componente que é agnóstico quanto ao estado da informação, é chamado de stateless.

De acordo com a conhecida restrição do REST, os componentes servidores são stateless, e toda a informação é armazenada em clientes stateful.

Os componentes do lado servidor são stateless, no sentido de que eles não armazenam informação de sessão entre as chamadas. Porém, isso é um pouco mais complicado e costuma causar muita confusão em relação à manutenção do estado no REST.

Vamos a um exemplo: Se um cliente armazena um objeto no servidor, o estado do servidor não muda? Ou ainda é RESTful, mesmo se referindo ao estado dos componentes no lado do servidor?

A confusão se ameniza quando percebemos que existem, na verdade, dois tipos de estado numa aplicação RESTful: o estado da aplicação e o estado do resource.

Estado da aplicação

O estado da aplicação é usado para manter o rastreamento das interações numa única instância de uma aplicação cliente. Ele não é compartilhado com as aplicações clientes, mas sim, dedicado com uma instância de aplicação única.

Em muitos sistemas não-REST, o estado da aplicação é assegurado por um objeto de sessão no servidor. Este objeto, por sua vez, pode ser criado ou alterado como resposta à chamada do cliente a uma funcionalidade do servidor.

Em sistemas REST, portanto, o estado da aplicação é armazenado apenas no lado cliente, e não do lado do servidor, ou seja, não na API.

As APIs não mantêm o estado da aplicação. Cada requisição da API deve ser independente das requisições anteriores. Esse é o motivo no qual todo request deve conter toda a informação necessária.

Esse princípio do modelo stateless assegura que a infraestrutura seja escalável com mais facilidade e de forma dinâmica (e o estado da aplicação não importará no momento da escalabilidade). 

Uma vez que o estado da aplicação é gerenciado pela aplicação cliente, a API consumidora necessita cuidar dessa característica, e é de responsabilidade dela construir clientes de acordo com esse padrão.

Estado do resource

O estado de resource representa o estado dos objetos de negócio, o qual se torna disponível como um resource REST. Ele é compartilhado por toda a aplicação e todas as instâncias.

Para compartilhar a informação, a única opção viável é o armazenamento do estado do resource no servidor. Assim, é de responsabilidade da API fornecer mecanismos para mudar o estado do resource. Inclusive, os métodos HTTPs POST, PUT, PATCH e DELETE são tipicamente usados para alterar o estado do resource via API.

< Continue aprendendo: Linguagens back-end: qual é a melhor opção para o seu projeto? />

Que tal aprofundar seus conhecimentos no desenvolvimento de APIs em REST?

Como vimos, o estilo REST é baseado no HTTP, o que lhe permite o uso de todas as vantagens deste protocolo. Porém, também carrega suas desvantagens.

Embora pareçam complicados à primeira vista, dominar tais conceitos, bem como a execução de tais processos, é vital para o sucesso na carreira de desenvolvedor.

Tendo isso em vista, conhecer boas práticas no desenvolvimento de APIs é fundamental para qualquer profissional que deseje se destacar no mercado.

E nós podemos te ajudar nesta jornada, com formações sólidas, que irão te preparar para o futuro. Conheça algumas opções:

• MBA em Desenvolvimento Full Stack;
• Trilha de especialização em Desenvolvimento Full Stack;
• Bootcamp online – Arquiteto(a) de Software;

Aproveite também para conhecer o XPE Multi+, o programa de assinatura da XP Educação, que está repleto de cursos, a fim de proporcionar uma formação contínua e consistente. É hora de desenvolver a sua carreira e se destacar no mercado!

Este texto foi escrito pelo professor Cristiano Santos Botelho. Se você gostou do conteúdo, não deixe de compartilhar com seus colegas, para que todos entendam os pormenores de como desenvolver uma API em REST.