API pra me servir

Imagine que você está com fome e precisa escolher em qual restaurante consumir. Cada restaurante tem seu próprio cardápio, com vantagens e desvantagens. Em cada página do menu há uma promoção diferente.

Trazendo isso para o mundo do desenvolvimento, cada restaurante seria uma API. O cardápio representa os endpoints disponíveis, e cada promoção seria uma rota específica que você pode pedir para receber um “combo” de respostas.

Interfaces facilitam

Uma API é como um balcão de pedidos: você faz uma solicitação e recebe a resposta já pronta, sem precisar se preocupar com o que acontece nos bastidores.

Requisição e Resposta

API -> Application Programming Interface (Interface de Programação de Aplicações) — um conjunto de regras que permite que softwares se comuniquem entre si.

Não curto essa definição, na minha mente sempre fica algo abstrato. Por isso, falou em API, já associo a um endereço onde faço pedidos e retornam respostas. Pra exemplificar, usando esse serviço do Méqui:

Vem ver o código... 
// Se eu quiser me servir no Méqui, vou no balcão,
// que é a interface para atendimento ao cliente.
// Falando com a atendente, ela me passa o acesso a API.
const API_DO_MEQUI = "https://ficticio.mequi.com/api/";

// Entre várias opções, escolho uma ROTA pra fazer meu pedido:

// Quero um Big Mac, tenho que ir no caminho dentro da api.
const bigMac = "https://ficticio.mequi.com/api/big-mac";

// Quero um Quarteirão de queijo, tenho que ir no caminho dentro da api.
// Obs: favorito desde sempre. 😋
const quarteirao = "https://ficticio.mequi.com/api/quarteirao";

// Quero só uma batatinha... vou até o caminho dentro da api.
const batatinha = "https://ficticio.mequi.com/api/batata";

Entendendo as definições

Continuando com o exemplo do Méqui, temos ali várias URLs com os endereços pra fazer os pedidos. Segmentando cada parte:

Vem ver o código... 
// O endereço que sempre se repete é a URL base.
const URL_BASE = "https://ficticio.mequi.com/api/";

// a ROTA é adicionada a URL base.
// https://ficticio.mequi.com/api/big-mac
const bigMac = URL_BASE + "big-mac";

// https://ficticio.mequi.com/api/quarteirao
const quarteirao = URL_BASE + "quarteirao";

// Mesmo exemplo, usando interpolação
// https://ficticio.mequi.com/api/batatinha
const rota = "batatinha";
const batatinha = `${URL_BASE}${rota}`;

Definindo cada termo quando falamos de API:

  • API: serviço que permite a comunicação entre sistemas.
  • Rota: caminho dentro da API que indica o recurso, ex: /api/quarteirao.
  • Endpoint: uso do método HTTP combinado com a rota, ex: GET https://ficticio.mequi.com/api/quarteirao.

Endpoints

Não quero deixar esse post muito técnico. O foco aqui é a abstração. Guarde contigo esse processo:

Toda vez que você como cliente usa um endpoint, você está fazendo um pedido, uma requisição para um servidor. O servidor irá te retornar uma resposta.

Como visto nas definições, o endpoint é a combinação entre o tipo de chamada que posso fazer e uma rota. Essas chamadas usam métodos, conhecidos como verbos HTTP. Em APIs Rest, os verbos mais comuns são: GET, POST, PATCH, PUT, DELETE.

Vem ver o código... 
// Rota fixa pra facilitar o exemplo.
const API_ROUTE_MEQUI_QUARTEIRAO = "https://ficticio.mequi.com/api/quarteirao";

// GET -> Método simples para consulta de dados.
const data = await callAPI('GET', API_ROUTE_MEQUI_QUARTEIRAO);

// Retorno dos dados com console.log(data) em JSON:
{
  "lanche": "Quarteirão com Queijo",
  "ingredientes": {
    "pao": "2 unidades",
    "carne": "1 hambúrguer bovino",
    "queijo": "2 fatias",
    "molho": "maionese especial",
    "batata": "porção média",
    "refrigerante": "coca-cola 300ml"
  },
  "preco": 52.90,
  "moeda": "BRL"
}

// POST -> Método que envia dados preenchidos no corpo da requisição.
const pedido = await callAPI('POST', API_ROUTE_MEQUI_QUARTEIRAO,
{
  pedido: "Quarteirão",
  quantidade: 2
});

// Retorno dos dados com console.log(pedido) em JSON:
{
  "status": "sucesso",
  "mensagem": "Pedido recebido: 2x Quarteirão",
  "pedidoId": "12345AB",
  "tempoEstimado": "15 minutos"
}

// PATCH -> Método para atualizar parte dos dados do pedido.
const atualizacao = await callAPI('PATCH', `${API_ROUTE_MEQUI_QUARTEIRAO}/12345AB`,
{
  quantidade: 1
});

// Retorno dos dados com console.log(atualizacao) em JSON:
{
  "status": "sucesso",
  "mensagem": "Quantidade atualizada para 1 no pedido 12345AB"
}


// PUT -> Método para substituir todos os dados do pedido.
const atualizacaoCompleta = await callAPI('PUT', `${API_ROUTE_MEQUI_QUARTEIRAO}/12345AB`,
{
  pedido: "Quarteirão Duplo",
  quantidade: 3
});

// Retorno dos dados com console.log(atualizacaoCompleta) em JSON:
{
  "status": "sucesso",
  "mensagem": "Pedido 12345AB atualizado para 3x Quarteirão Duplo"
}

// DELETE -> Método para cancelar/remover o pedido
const exclusao = await callAPI('DELETE', `${API_ROUTE_MEQUI_QUARTEIRAO}/12345AB`);

// Retorno dos dados com console.log(exclusao) em JSON:
{
  "status": "sucesso",
  "mensagem": "Pedido 12345AB cancelado com sucesso"
}


// Função auxiliar, simulando as chamadas HTTP no exemplo.
async function callAPI(verb, route, body = null) {
  const options = { method: verb };
  if (body) {
    options.body = JSON.stringify(body);
    options.headers = { 'Content-Type': 'application/json' };
  }
  const response = await fetch(route, options);
  return response.json();
}

Bom, eu fico por aqui. Espero ter deixado alguns exemplos didáticos, que ajudem na compreensão sobre API’s.

Bons estudos e bons códigos!

Referências

O que são APIs Rest?
Métodos para requisições HTTP
JSON Placeholder - API gratuita para testar
ReqBin - Faça requisições para uma API
JSON Viewer - Extensão para visualizar JSON no Chrome

➡️ Mais artigos…