Até o início desse ano nunca tive a oportunidade de trabalhar com a criação e manutenção de APIs. Apesar de vir fazendo projetos com Django desde 2017, API, pra mim, era igual caviar.
Veja, ao menos o básico eu achava que sabia! Se você me perguntasse em dezembro de 2020 o que era uma API, eu lhe diria: "É o jeito de abrir as portas da sua aplicação para o mundo. Em vez de retornar um HTML, você vai ter que retornar um JSON com os dados."
Essa antiga visão não estava totalmente certa, mas também não estava 100% errada.
Hoje eu definiria uma API como um protocolo de comunicação entre sistemas. Essa comunicação pode OU NÃO ser através do JSON (podemos usar até TXT, se quisermos. Contanto que haja um padrão de comunicação).
De onde peguei esses níveis de maturidade de uma API
Em Janeiro de 2021, fui contratado para trabalhar como desenvolvedor backend Django na empresa Fastzap do Gabriel Freitas.
No produto do Gabriel, assim como na maioria das empresas, o backend é separado do frontend. Logo, eu teria que trabalhar fazendo API para o frontend (VueJS) consumir.
Logo que fui contratado, por saber só o básico de API, comprei alguns cursos sobre Django Rest Framework (DRF), que era o que eu acabaria utilizando na empresa.
Um dos cursos que comprei foi o Design de API na Prática, do Henrique Bastos. Um curso ótimo que vai destrinchando o que é uma API e como ir criando e evoluindo, pouco a pouco, até chegar no "modelo final".
(Coloquei a ultima palavra entre aspas, pois nunca se chega a um modelo final. Um software é um organismo vivo em constante evolução)
No curso, o Henrique apresentou os conceitos de níveis de maturidade de uma API. Foram 4 níveis, do 0 até o 3.
Nível 0
Esse nível é quando a comunicação é feita meio que de forma desorganizada e sem padrões algum. Nesse nível, as APIs, geralmente, não usam de forma correta os verbos do HTTP, não usam adequadamente a URI e nem usa os conceitos de Hipermídia/hiperlink.
Veja abaixo um exemplo desse nível:
Veja que não há o uso correto do verbo, nem da URI. Baseado nos parametros é que o servidor vai delegar para função X ou Y.
Nível 1
Nesse estágio de maturidade, já começamos a ver um uso melhor da URI. Então, temos endpoints separados para fazer determinadas ações. Porém, ainda sem usar muito dos verbos HTTP (no máximo um GET e POST) e os status de retorno da requisição podem não seguir o padrão. Ex.: retornar sempre status 200 para qualquer solicitação.
Veja o exemplo:
Já começamos ver uma evolução nesse nível. As coisas já começam a ficar organizada e, visualmente, você já sabe o que o endpoint vai fazer com a requisição.
O nível 1 é bastante utilizado hoje em dia!!! Já vi em vários lugares um POST fazer alteração de um dado ou um GET ter algum efeito no BD.
Nível 2
Juntamente com o nível 1, esse é um dos níveis mais utilizados. A diferença desse nível de maturidade para o anterior é: O nível 2 já trabalha com os verbos do HTTP de maneira correta e, principalmente, com os status de resposta da requisição corretamente.
Através do uso desses métodos, podemos ver algo mais organizado como da seguinte forma:
Você pode conferir a descrição oficial de todos os verbos HTTP no site da Mozilla.
Nível 3
O nível 3 é o nível mais alto nível que tem. Ele implementa uma boa padronização na URI, usa adequadamente os verbos do HTTP e seus respectivos status de retono. No entanto, ele possui uma diferença: O nível 3 de maturudade utiliza Hipermídia/hiperlinks.
Visualmente, as requisições são bastante parecidas (pra não dizer igual) ao nível 2 de maturidade. O que muda é a resposta!!
Agora, fica de responsabilidade do backend dizer quais são as ações que o front pode tomar para aquele recurso. Veja um exemplo de uma resposta de uma requisição POST para /produtos/
{
"id": "fddba6e3-d87c-4b39-9d7d-18ebf1e38cef",
"name": "Gasolina",
"price": {
"value": "7,00",
"currency": "BRL"
},
"actions": [
{
"name": "self",
"link": "https://api.com/product/fddba6e3-d87c-4b39-9d7d-18ebf1e38cef",
"method": "GET"
},
{
"name": "update",
"link": "https://api.com/product/fddba6e3-d87c-4b39-9d7d-18ebf1e38cef",
"method": "PUT"
},
{
"name": "delete",
"link": "https://api.com/product/fddba6e3-d87c-4b39-9d7d-18ebf1e38cef",
"method": "DELETE"
},
{
"name": "shop",
"link": "https://api.com/product/fddba6e3-d87c-4b39-9d7d-18ebf1e38cef/shop",
"method": "POST"
},
]
}
Perceba que dessa forma retiramos toda a complexidade de gerenciar isso no front. Quanto menos o frontend souber das regras do backend, melhor será de consumir a API.
No exemplo acima, eu coloquei uma lista de ações e especifiquei até o método de cada URI. Mas não precisa ser assim! Só de retornar a URI no resposta, já tá valendo. Ter Hipermídia e Hiperlink na URI já se configura um nível 3 de maturidade na sua API.
Veja também como que ficou fácil navegar entre a API. É quase como se fosse um HTML, onde você vai navegando entre os links. Isso facilita muito quando você tem uma aplicação com front web, front mobile, front na TV, front no relógio e até na geladeira!
Conclusão
As APIs possuem 4 níveis de maturidade. No entanto, cabe ao programador escolher de que modo vai resolver o problema. Desde que ele saiba o que está fazendo, pode escolher qualquer nível de maturidade.
Foto da capa by Douglas Lopes on Unsplash .