Aprendendo mais sobre API's

Table Of Contents

• Porque aprender mais sobre API's
• O que é uma API
• APIREST
• Controller-Services-Repository
• Headers-Verbos
• Parâmetros

 

Porque aprender mais sobre API's

Meu primeiro contato com API's não faz muito tempo mas foi algo meio estranho, sempre me pareceu que era uma coisa muito mais complexa do que parecia ser (e é), mas nunca tive curiosidade o suficiente para ir afundo, afinal, eu dava o fetch na URL, fazia um GET me voltava o json que eu queria e eu manipulava isso a meu bel prazer ou eu conseguia fazer um POST simples voltava o status code 200 e ta pronto o sorvetinho.

Essa semana precisei testar uma API privada do 0 e ver o que era possível fazer com os métodos disponíveis e, não sei se por inexperiência minha, ou se a plataforma que eu estava usando não ajudou (talvez um misto dos dois), eu não consegui testar muita coisa, afinal, tinha um conhecimento extremamente raso sobre API's e com isso, decidi estudar e ir mais afundo, continuo com o conhecimento raso, mas agora entendo um pouco melhor sobre API's, o que são e suas funcionalidades, vou escrever esse artigo para fixar melhor as informações que aprendi essa semana, se isso conseguir ajudar alguém que, por ventura, esbarre em dificuldades semelhantes as que eu tive então sera uma vitoria dupla!

Alguns disclaimers necessários:

• Boa parte do que aprendi aqui, aprendi pesquisando em diversas fontes mas a mais rica e que mais me agregou conhecimento foi o Curso de testes de API Rest do Julio de Lima, se esse conteúdo te ajudar de qualquer forma, peço que fortaleça o canal dele se inscrevendo e dando like nos vídeos, a quantidade e qualidade de conteúdo sobre testes que ele faz merece ser reconhecida e retribuída de alguma maneira

• Caso encontre algo de errado escrito aqui, desde conceitos ate erros gramaticais, por favor, me avise (seja por comentários, twitter etc)

 
 

O que é uma API

Ao pé da letra, API significa "Application Programming Interface", traduzido ficaria, "Interface de Programação de Aplicativos", a principio esse conceito não ficou tão claro pra mim então comecei a pesquisar mais e ler mais sobre como outras pessoas "definiam" uma API.

O próprio Julio em um dos videos dele deu a explicação que eu achei mais didática e clara possível, se temos o UI/UX, que se trata sobre a User Interface (Interface do Usuário) e User Experience (Experiencia do Usuário), podemos pensar na API como uma UI, mas voltada ao software que irá utilizá-la, onde, ao se pensar no UI, se pensa em uma pessoa vendo aquela interface e o quão intuitiva ela é, na API se pensa em, o quão "intuitivo" sera para outros softwares interagirem com o que aquela API oferece!

O software não precisa saber (geralmente) em que linguagem a API foi escrita, ele só precisa saber o tipo de resultado que ela ira gerar, o resto é abstraído, apenas o resultado importa, da mesma forma que você não precisa saber o que acontece embaixo dos panos do dev.to, você veio ler o texto apenas.

 
 

APIREST/RESTful

Esse tópico com certeza merece um artigo só para dissecar o tanto de coisa que tem para ser entendida sobre REST, mas fica para a proxima, só de ter a noção do que é uma APIRest já ajuda a entender melhor sobre tudo isso.

O ponto central sobre REST (sigla para Representational State Transfer ou Transferência de Estado Representacional) é ser um modelo/estilo de arquitetura definido pela W3C, um dos seus principais conceitos é utilizar o protocolo HTTP (verbos, accept headers, códigos de estado HTTP etc) de forma explícita e representativa para se comunicar e geralmente utilizar arquivos JSON e XML para a transferencia de dados.

Isso significa que, se você já mexeu com uma APIRestful, APIs que seguem esse estilo de arquitetura, você consegue ter noção sobre como outras API's com essa arquitetura funcionam.

 
 

Controller-Services-Repository

Geralmente dentro de uma APIRest nos temos essas três "entidades" fazendo com que ela seja funcional e definindo elas seria mais ou menos assim:

Services

• Geralmente é a camada do backend que armazena as regras de negocio

Repositories

• Responsável por trafegar as informações entre a regra de negocio e o sistema de armazenamento/banco de dados

Controller

• Intermediador entre quem chama (aplicação que vc esta utilizando) e os serviços e repositórios
• Disponível via HTTP, geralmente
• Controla autenticação/autorizações
• Recebe endpoints via anotações
• Define os métodos/verbos necessários para acessar as funções

Um fluxo simulando a utilização de uma API seria mais ou menos assim:

- Interface Grafica => Controller => Services => Repository => Database

Seu site/interface grafica faz a requisição a API pelo controller, que envia a requisição ao services que envia o que foi solicitado ao Repository que ai vai consultar/enviar as informações para o banco de dados/database e então:

- Interface Grafica <= Controller <= Services <= Repository <= Database

Fazer o caminho contrario, o Database, envia o resultado da sua requisição para o Repository, que envia para o Services, que envia para o Controller e este te da uma resposta em JSON ou XML!

 
 

Headers-Verbos

Cabeçalho e Headers são dois métodos do protocolo HTTP que são utilizados em requisições numa APIRest, detalhando um pouco mais sobre eles teríamos:

Headers

• Informações técnicas para ajudar o servidor a entender o que está sendo enviado naquela requisição

• Authorization geralmente vai no header da requisição

Verbos

As ações que aquela requisição deseja fazer, geralmente as mais utilizadas são:

• POST - Criar uma nova informação no backend, pode ser usado também para enviar informações sensíveis utilizando o protocolo HTTPS para criptografar a informação, por exemplo, para autenticar um usuário.
• GET - Buscar uma informação no backend
• PUT - Atualizar uma informação no backend
• DELETE - Deletar uma informação no backend

Exemplo de requisição via CURL

curl -X POST -is "https://api.github.com/user/repos" -H 'Authorization: token <token>' -H 'Content-Type: application/json' -d '{"name": "teste-api-swagger"}'

onde:

• curl é uma ferramenta/biblioteca por linha de comando para transferência de data via URL

• -X declara qual verbo/método sera feito, nesse caso POST para autenticação

• -i é o método indicando que, queremos ver as informações do cabeçalho que a nossa resposta retorna

• -s é o método indicando que, não queremos ver as informações sobre quanto tempo demorou para download e quanto tempo demorou para processar

• -H significa que as informações em "" são informações referentes ao header da requisição, nesse caso, a Autorização via token e o content-type indicando que estamos enviando um json

• -d é o body da nossa requisição, o conteúdo dela por assim dizer

 
 

Parâmetros

Nas requisições, há algumas formas de se passar parâmetros e assim conseguir respostas de acordo com a sua necessidade, podemos passar parametros pelo body da requisição, pelo header, pelo query ou pelo path dela

• Body:
  Usando o -d dentro do curl ex: -d '{"name": "teste-api-swagger"}

• Header:
  Usando o -H dentro do curl, com aspas simples -H 'Authorization: chave de autorização da API'

• Query:
  Depois do endpoint, usando o ? e o & caso tiver mais de um parâmetro, "ex: localhost:3000/users?id=1&name=teste"

• Path:
  Depois do endpoint, colocando um / antes do nome do parametro, "ex: localhost:3000/users/1"

Comments

[Vinícius Neto]

muito massa o artigo Sergio, ficou numa linguagem bem acessível e de boas de entender!

[Jonatas Pinto Ferreira]

Obrigado pela contribuição! 👏

[Murilo Menezes Mendonça]

no body o "-d" é de "data"?

[Sergio]

eu presumo que sim, assim como o -H é de Header