0Pricing
R Academy · Aula

Consumindo APIs REST em R

Faça autenticação com chaves de API, pagine os resultados e armazene as respostas da API.

Consumindo APIs REST em R é uma aula grátis de R Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de R Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de R Academy inclui 4 aulas no total.

Conceitos de APIs REST

As APIs REST usam métodos HTTP (GET, POST, PUT, DELETE) em URLs de recursos. As respostas geralmente são JSON. As APIs podem exigir autenticação, lidar com paginação e impor limites de taxa. Um bom cliente de API em R trata desses três aspectos.

library(httr2)

# REST API anatomy:
# Base URL:  https://api.example.com/v1
# Resources: /users, /products, /orders
# Methods:
#   GET    /users       -> list users
#   POST   /users       -> create user
#   GET    /users/42    -> get user 42
#   PUT    /users/42    -> update user 42
#   DELETE /users/42    -> delete user 42

# Query parameters for filtering/pagination:
# GET /users?page=2&size=20&sort=name

cat('REST = stateless + resource-based + HTTP methods')

Autenticação com token Bearer

A maioria das APIs modernas usa tokens Bearer (OAuth 2.0). Armazene o token em uma variável de ambiente com Sys.setenv() ou em um arquivo .Renviron. Nunca grave tokens diretamente nos scripts.

library(httr2)

# Store token securely in .Renviron:
# GITHUB_PAT=ghp_your_token_here

# Access at runtime:
token <- Sys.getenv('GITHUB_PAT')
if (nchar(token) == 0) token <- 'demo_token'

# Use in requests:
# resp <- request('https://api.github.com/user') |>
#   req_auth_bearer_token(token) |>
#   req_headers('Accept' = 'application/vnd.github.v3+json') |>
#   req_perform() |>
#   resp_check_status()

# result <- resp_body_json(resp)
# result$login  # your GitHub username
cat('Token from env:', if(nchar(token)>0) 'found' else 'missing')

Construindo um cliente de API reutilizável

Encapsule a URL base, a autenticação e o tratamento de erros em uma função construtora. Cada ponto de acesso da API se torna um método que chama essa função base — esse é o padrão comum em pacotes de API para R.

library(httr2)

# API client constructor
new_api_client <- function(base_url, token) {
  list(
    base_req = request(base_url) |>
      req_auth_bearer_token(token) |>
      req_headers('Accept' = 'application/json') |>
      req_retry(max_tries = 3)
  )
}

# Method: GET /users
get_users <- function(client, page = 1, size = 20) {
  resp <- client$base_req |>
    req_url_path_append('users') |>
    req_url_query(page = page, size = size) |>
    req_perform() |>
    resp_check_status()
  resp_body_json(resp, simplifyVector = TRUE)
}

# client <- new_api_client('https://api.example.com', token)
# users <- get_users(client, page = 1)
cat('Reusable client pattern: base request + methods')

Paginação com resp_link_url()

Muitas APIs usam cabeçalhos Link para paginação (RFC 5988): a resposta inclui um cabeçalho Link: <url>; rel="next". resp_link_url(resp, 'next') extrai automaticamente a URL da próxima página.

library(httr2)

# Generic paginator using Link headers
fetch_all_pages <- function(initial_url, token, max_pages = 50) {
  all_results <- list()
  next_url <- initial_url
  page <- 1
  while (!is.null(next_url) && page <= max_pages) {
    resp <- request(next_url) |>
      req_auth_bearer_token(token) |>
      req_perform() |>
      resp_check_status()
    all_results[[page]] <- resp_body_json(resp, simplifyVector = TRUE)
    # Follow Link: <url>; rel='next' header
    next_url <- tryCatch(
      resp_link_url(resp, 'next'),
      error = function(e) NULL
    )
    page <- page + 1
  }
  do.call(rbind, all_results)
}
cat('resp_link_url() follows RFC 5988 pagination')

Paginação baseada em cursor

Algumas APIs, como Twitter e Slack, usam cursores em vez de números de página. A resposta inclui um campo next_cursor ou next_page_token. Passe esse valor como parâmetro de consulta na próxima requisição.

library(httr2)

# Cursor-based pagination pattern
fetch_cursor_pages <- function(base_url, token, max_pages = 100) {
  all_data <- list()
  cursor <- NULL
  page <- 1
  repeat {
    req <- request(base_url) |>
      req_auth_bearer_token(token)
    if (!is.null(cursor))
      req <- req |> req_url_query(cursor = cursor)
    resp <- req |> req_perform() |> resp_check_status()
    body <- resp_body_json(resp)
    all_data[[page]] <- body$results
    cursor <- body$next_cursor  # NULL if last page
    if (is.null(cursor) || page >= max_pages) break
    page <- page + 1
  }
  do.call(c, all_data)
}
cat('Cursor pagination: safer for large/changing datasets')

Tratando erros de forma adequada

Um cliente de API usado em produção captura separadamente os erros HTTP e as falhas de rede. Use tryCatch() ao redor de req_perform() e inspecione a condição de erro httr2_http_* para um tratamento específico por status.

library(httr2)

safe_api_call <- function(req) {
  tryCatch(
    req |> req_perform() |> resp_check_status(),
    httr2_http_401 = function(e) {
      stop('Authentication failed. Check your token.')
    },
    httr2_http_403 = function(e) {
      stop('Forbidden. Insufficient permissions.')
    },
    httr2_http_404 = function(e) {
      message('Resource not found, returning NULL')
      return(NULL)
    },
    httr2_http_429 = function(e) {
      stop('Rate limit exceeded. Try again later.')
    },
    error = function(e) {
      stop(paste('Request failed:', conditionMessage(e)))
    }
  )
}
cat('Match on specific httr2_http_NNN conditions')

Armazenando respostas de APIs em cache

Armazene as respostas das APIs em cache para evitar requisições desnecessárias durante o desenvolvimento. req_cache(), no httr2, armazena as respostas em disco respeitando os cabeçalhos Cache-Control. O armazenamento manual em cache funciona com qualquer API.

library(httr2)

# httr2 built-in disk cache
# resp <- request('https://api.example.com/static-data') |>
#   req_cache(tempdir(), max_age = 3600) |>  # 1 hour TTL
#   req_perform()

# Manual cache pattern
cached_api_call <- function(url, cache_file, max_age = 3600) {
  if (file.exists(cache_file)) {
    age <- as.numeric(Sys.time() - file.mtime(cache_file))
    if (age < max_age) {
      cat('Cache hit\n')
      return(readRDS(cache_file))
    }
  }
  cat('Cache miss, fetching...\n')
  # result <- resp_body_json(request(url) |> req_perform())
  # saveRDS(result, cache_file)
  # result
}
cached_api_call('https://example.com/api', 'cache.rds')

Requisições paralelas com req_perform_parallel()

req_perform_parallel() envia várias requisições simultaneamente, reduzindo drasticamente o tempo total de operações em lote. Combine-o com req_throttle() para respeitar os limites de taxa durante a execução paralela.

library(httr2)

# Build a list of requests
item_ids <- 1:5
reqs <- lapply(item_ids, function(id) {
  request(paste0('https://jsonplaceholder.typicode.com/todos/', id))
})

# Execute all in parallel (requires internet)
# resps <- req_perform_parallel(
#   reqs,
#   on_error = 'continue',  # skip failures
#   progress = TRUE
# )
# results <- lapply(resps, resp_body_json)
# titles <- sapply(results, function(r) r$title)
# print(titles)

# on_error options:
# 'stop'     -> abort on first failure
# 'continue' -> collect errors, keep going
cat('Parallel: much faster for many independent calls')

Trabalhando com limites de taxa

As APIs comunicam o estado dos limites de taxa por meio dos cabeçalhos de resposta: X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After. Leia esses valores para implementar um recuo progressivo inteligente.

library(httr2)

respect_rate_limit <- function(resp) {
  # Check remaining calls
  remaining <- resp_header(resp, 'x-ratelimit-remaining')
  if (!is.na(remaining) && as.integer(remaining) < 5) {
    reset_at <- as.integer(
      resp_header(resp, 'x-ratelimit-reset')
    )
    wait_secs <- max(0, reset_at - as.integer(Sys.time()))
    cat(sprintf('Rate limit nearly exhausted. Waiting %ds\n', wait_secs))
    # Sys.sleep(wait_secs)
  }
  # Handle 429 Retry-After header
  if (resp_status(resp) == 429) {
    retry_after <- resp_header(resp, 'retry-after')
    cat(sprintf('Rate limited. Retry after %s seconds\n', retry_after))
  }
  resp
}
cat('Always respect X-RateLimit-* headers')

Cliente de API completo: exemplo com GitHub

Juntando tudo: um cliente completo da API do GitHub que faz autenticação, busca listas paginadas de repositórios e trata erros — demonstrando todos os padrões aprendidos até agora.

library(httr2)

# GitHub API client
github_repos <- function(username, token = NULL, n_pages = 3) {
  base <- 'https://api.github.com'
  req_base <- request(base) |>
    req_headers(
      'Accept'     = 'application/vnd.github.v3+json',
      'User-Agent' = 'R-API-Client/1.0'
    )
  if (!is.null(token))
    req_base <- req_base |> req_auth_bearer_token(token)

  all_repos <- list()
  for (page in seq_len(n_pages)) {
    # resp <- req_base |>
    #   req_url_path_append('users', username, 'repos') |>
    #   req_url_query(page = page, per_page = 30, sort = 'updated') |>
    #   req_perform() |> resp_check_status()
    # repos <- resp_body_json(resp, simplifyVector = TRUE)
    # if (length(repos) == 0) break
    # all_repos[[page]] <- repos
    cat(sprintf('Would fetch page %d for %s\n', page, username))
  }
  do.call(rbind, all_repos)
}
github_repos('hadley')

Credenciais de cliente OAuth 2.0

Algumas APIs exigem o fluxo de credenciais de cliente do OAuth 2.0: trocar client_id + client_secret por um token de acesso. oauth_client() e req_oauth_client_credentials() do httr2 cuidam disso automaticamente.

library(httr2)

# OAuth 2.0 Client Credentials flow:
# client <- oauth_client(
#   id     = Sys.getenv('CLIENT_ID'),
#   secret = Sys.getenv('CLIENT_SECRET'),
#   token_url = 'https://auth.example.com/oauth/token'
# )

# Automatic token management:
# resp <- request('https://api.example.com/data') |>
#   req_oauth_client_credentials(client) |>
#   req_perform()
# httr2 automatically:
# 1. Gets access token using client credentials
# 2. Adds 'Authorization: Bearer <token>' header
# 3. Refreshes token when expired

cat('req_oauth_client_credentials() handles token lifecycle')
cat('Token is cached in memory automatically')

Verificação rápida

Teste sua compreensão sobre a construção de clientes de APIs REST em R com httr2.

Recapitulação: consumindo APIs REST

Principais conclusões: construa clientes reutilizáveis encapsulando a URL base, a autenticação e as novas tentativas em uma função construtora. Use req_auth_bearer_token() para autenticação — armazene os tokens em variáveis de ambiente. Lide com a paginação por meio de cabeçalhos Link com resp_link_url() ou de padrões baseados em cursor. Sempre trate os erros HTTP com resp_check_status() e tryCatch(). Use req_perform_parallel() para chamadas em lote. Armazene os resultados em cache durante o desenvolvimento.

library(httr2)

# REST API client template:
make_api_call <- function(url, token,
                          method = 'GET',
                          body = NULL,
                          query = list()) {
  req <- request(url) |>
    req_method(method) |>
    req_auth_bearer_token(token) |>
    req_headers('Accept' = 'application/json') |>
    req_retry(max_tries = 3) |>
    req_throttle(rate = 10/60)
  if (length(query) > 0)
    req <- do.call(req_url_query, c(list(req), query))
  if (!is.null(body))
    req <- req |> req_body_json(body)
  req |> req_perform() |> resp_check_status()
}
cat('Template: auth + retry + throttle + error check')

Perguntas Frequentes

A aula “Consumindo APIs REST em R” é grátis?

Sim — o texto completo de “Consumindo APIs REST em R” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de R Academy, atualize para CoddyKit PRO. O curso de R Academy inclui 4 aulas no total.

O que vou aprender em “Consumindo APIs REST em R”?

Faça autenticação com chaves de API, pagine os resultados e armazene as respostas da API. Você pratica R Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar R Academy?

Nenhuma experiência prévia é necessária. R Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Consumindo APIs REST em R”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de R Academy?

Sim. Cada aula de R Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Analisando JSON com jsonlite
  2. Fazendo solicitações HTTP com httr2
  3. Consumindo APIs REST em R
  4. Lidando com estruturas JSON aninhadas
← Voltar para R Academy