Este tópico visa fomentar o conhecimento na nossa comunidade, principalmente no que tange aos conceitos gerais relacionados a APIs, e fornecer uma apresentação dos principais termos e exemplos de respectivas APIs no contexto VTEX.
O que são APIs?
Conceituação formal
API significa Application Programming Interface (Interface de Programação de Aplicação)
Na prática, são mecanismos que permitem que dois componentes de software se comuniquem usando um conjunto de definições e protocolos.
Conceituação visual
Imagine que existam dois sistemas cuja interação requer alguma troca de informações ou comandos. Considere também que esses sistemas possuem subprocessos com alguma semelhança ou relação, e esses subprocessos precisam estabelecer comunicação com o segundo sistema.
Uma forma de construir essa ponte é através do uso de APIs
Ainda que as estruturas dos dois sistemas não sejam iguais, diferentes módulos no segundo sistema podem se beneficiar de uma conexão com outros do primeiro sistema. Como um processo de dados encaminhar informações para um processo de relatórios, por exemplo.
Importante destacar que essa comunicação por vezes pode acontecer em duas vias, mas não são raros casos em que um sistema é passivo e apenas irá processar as requisições recebidas. Um exemplo é a relação da VTEX com ERPs, nós recebemos por API as requisições do ERP, mas não enviamos requisições ao ERP. Logo, seria um exemplo do desenho acima, e não do seguinte.
O que são métodos de uma API?
Os métodos são os tipos de requisições que a API podem fazer. Eles precisam ser declarados durante a requisição e cada um terá suas particularidades. Vejamos os mais comuns:
GET
GET é um tipo de requisição que consulta informações, sua função é acessar um dado guardado pelo sistema de destino.
Exemplos de GETs comuns no dia a dia da VTEX:
POST
No POST uma nova informação é inserida no sistema de destino, esse é um dado novo que pode ser a criação de um novo cliente em uma base de clientes ou um novo pedido, por exemplo.
Exemplos de POSTs comuns no dia a dia da VTEX:
PUT
O PUT é semelhante ao POST no que se diz respeito a preencher informações, mas ele atualiza uma informação em uma estrutura já existente, diferente do POST que efetivamente cria uma nova instância de algo.
Exemplos de PUTs comuns no dia a dia da VTEX:
PATCH
O PATCH é semelhante ao PUT, mas é mais seletivo quanto à atualização. Enquanto no PUT é necessário passar todos os parâmetros, no PATCH é possível selecionar qual parâmetro deve ser atualizado e alterar apenas ele.
Exemplos de PATCHs comuns no dia a dia da VTEX:
DELETE
O DELETE, como o nome sugere, exclui um dado antigo sem substituí-lo por uma informação nova.
O que são Endpoints?
Endpoints são as URLs, ou endereços, para onde será enviada a requisição. Assim como o método, o Endpoint é para estabelecer comunicação com a API.
Os Endpoints podem ter parâmetros, identificados entre { } que apontam para o local correto a se requerer. Por exemplo, se eu quero consultar um preço, preciso indicar no Endpoint de qual conta estou falando e a qual item pertence esse preço.
O que são Headers?
Headers são parâmetros mais abrangentes que aqueles presentes no Endpoint, eles dizem respeito não à rota, mas aos critérios obrigatórios para chegar ao destino. O melhor exemplo para visualizar isso é entender que a autenticação é passada através do Headers, para realizar a requisição você precisa passar suas credenciais, e o local dedicado para isso são os Headers. Mas não se limitam a isso, coisas como Qual o formato aceito de conteúdo? ou Chaves de paginação de resultados também podem ser passados via Headers.
O que é o Body?
Para métodos como o POST, PUT e PATCH, há um envio de informações, essas informações são passadas via JSON (objetos), e esse corpo contendo o detalhamento das informações é chamado de body da requisição. Na documentação das nossas APIs, fornecemos exemplos de quais os formatos aceitos para o body de cada API. Visto que passar o body de forma inesperada acarretará em erro na requisição.
Destacado na caixa vermelha está um modelo de Body que é aceito para essa requisição, os valores das variáveis podem ser mudados, obedecendo o formato, mas os nomes das variáveis precisa ser preservado.
O que é cURL?
cURL é o conjunto de todas essas informações: Método, Endpoint, Headers e Body. Com ele é possível realizar de forma completa a requisição. Um exemplo seria o seguinte:
Veja que há uma combinação de todos os elementos, bastando completar com sua autenticação e editar o body para ser capaz de realizar a requisição.
Para saber qual o passo a passo prático para realizar requisições, consulte esse tópico aqui mesmo na Community: Dúvidas Frequentes: Como utilizar APIs? | Passo a passo inicial de como utilizar as APIs do Developers e aplicar na sua loja VTEX
Cleber Feitosa
Field Software Engineer | VTEX