APIs REST - Dicas básicas e boas práticas - I

Hoje vamos iniciar a apresentação de dicas básicas e das principais boas práticas que podemos usar para criar e usar APIs Restful, ou seja, aderentes ao estilo REST.

Atualmente a utilização de APIs RESTful é bem difundida e dentro diversos fatores que contribuíram para isso podemos destacar o fato do REST ser bastante flexível e compatível com HTTP, que é o principal protocolo no qual a Internet se baseia.

Como é um estilo de arquitetura e não um padrão, o REST oferece muita liberdade para implementar várias práticas recomendadas de design. Além disso o REST é agnóstico quanto à linguagem usada na implementação.

Assim creio que vale a pena analisar alguns conceitos básicos e definições e também mostrar algumas práticas recomendadas na criação de APIs REST.

O que é REST ?

REST significa Representational State Transfer e é um estilo arquitetônico fundado por Roy Fielding, e,  é usado principalmente para realizar a comunicação entre sistemas na Internet.

O REST está vinculado ao protocolo HTTP ?

Por definição, não esta.

Embora você possa usar qualquer outro protocolo com o REST, o HTTP é de longe o mais usado nas implementações do REST.

Suporte REST e HATEOAS

HATEOAS significa - Hypermedia As The Engine Of Application State - ou Hipermídia como o estado do mecanismo do aplicativo, e é uma restrição que faz parte da arquitetura REST.

O HATEOAS foi desenvolvido por Leonard Richardson e traz o modelo REST para um novo nível, cujo objetivo é ajudar os clientes que consomem o serviço REST, a navegar pelos recursos e saber o que podem fazer, tornando assim as ações da API mais fáceis de entender.

Usando HATEOAS a resposta da API acrescenta também links descritivos que servem para informar como você pode alterar o recurso e informações de como buscar recursos secundários ou relacionados.

Para detalhes veja o meu artigo : NET - Apresentando HATEOAS - Macoratti.net

O que significa o termo 'Restful API' ?

Quando dizemos que uma API é Restful significa dizer que ela é aderente ao estilo REST.

Para uma API ser Restful ela tem que ser aderente às restrições definidas pelo estilo REST como:

Portanto, uma API RESTful é um serviço que tem que seguir essas restrições, e, usa métodos HTTP para manipular o conjunto de recursos.  Os principais métodos HTTP usados são : GET, POST, PUT e DELETE.
Mas por que precisamos ou usamos APIs RESTful?

Porque as APIs REST oferecem uma maneira fácil, flexível e escalável de criar aplicativos distribuídos que se comunicam pela Internet.

As APIs REST não são a 'bala de prata' ou panacéia universal das APIs mas elas são simples e funcionam e atendem uma grande gama de cenários onde resolvem o problema existente.

Desta forma, precisamos de um pouco de pragmatismo para criar bons aplicativos e serviços, e, para isso é importante conhecer e entender uma teoria, mas a implementação dessa teoria é o que diferencia aplicações ruins das aplicações boas e estas das excelentes. Portanto, seja inteligente, tenha em mente o usuário final.

Imbuídos deste espírito iremos seguir adiante, agora definindo dicas e boas práticas indicadas para a criação de APIs Restful.

Por hoje vou deixar um link para uma API Restful que você vai poder explorar e usar fazendo algumas chamadas e vendo o resultado.

Segue o link:  https://reqres.in/

Continuamos na próxima parte do artigo.

"O entendimento para aqueles que o possuem, é uma fonte de vida, mas a instrução dos tolos é a sua estultícia."
Provérbios 16:22

Referências:

José Carlos Macoratti