DOCSEARCHbyAlgolia
Submit Docs

httr2

repository·main·Indexed 42 days ago

https://github.com/r-lib/httr2

A modern, pipeable HTTP client for R built on top of curl. It features explicit request objects, built-in rate limiting, retry tooling via req_retry(), comprehensive OAuth support, and secure secret management.

Tokens
1.1K
Snippets
5
Records
6
Agent score
5%

What's inside httr2

  1. Major differences between httr and httr2

    main

    If you are migrating from httr, note these key architectural changes:

    • Request/Response Separation: In httr2, you create and modify request objects independently before performing them. req_perform() replaces the individual httr::GET(), httr::POST(), etc., functions.
    • Error Handling: HTTP errors (4xx and 5xx) are automatically converted into R errors. You can use req_error() to customize this behavior.
    • Built-in Retries: req_retry() provides native support for automatic retries on transient failures.
    • Enhanced OAuth: The OAuth implementation has been overhauled to support more flows and easier customization.
    • Secret Management: Includes tools like secret_encrypt() for managing credentials and obfuscate() for protecting sensitive data in code.

  3. Basic usage of httr2

    main

    The httr2 workflow follows a pattern of creating a request object, modifying it using the req_ family of functions, and finally performing the request with req_perform().

    1. Create a request: Use request(url) to initialize an <httr2_request> object.
    2. Modify the request: Use pipeable functions like req_headers(), req_body_json(), or req_method() to tailor the request.
    3. Perform the request: Use req_perform(req) to execute the request and receive an <httr2_response> object.
    4. Extract response data: Use resp_ functions to parse the response content.
    library(httr2)

# 1. Create
req <- request("https://r-project.org")

# 2. Modify (example: adding a header)
req <- req |> req_headers("Accept" = "application/json")

# 3. Perform
resp <- req_perform(req)

# 4. Extract
content_type <- resp |> resp_content_type()

  4. Modify requests with the req_ family

    main

    The req_ family of functions allows you to transform an <httr2_request> object. These functions are designed to be used in a pipe (|>).

    Common modification tasks include:

    • Add custom headers: req_headers(...)
    • Add a body: req_body_json(...) (this automatically changes the method to POST)
    • Modify the URL path: req_url_path(path = "...")
    • Change the HTTP method: req_method("METHOD")
    • Configure retries: req_retry(max_tries = ...)
    • Preview the request: req_dry_run() shows exactly what will be sent to the server without actually making the call.
    # Example of a complex request construction
req <- request("https://r-project.org") |
  req_headers("Accept" = "application/json") |
  req_body_json(list(x = 1, y = 2)) |
  req_url_path(path = "path/to/my/file") |
  req_method("PATCH") |
  req_retry(max_tries = 5)

# Preview what will be sent
req |> req_dry_run()

  5. Handle responses with resp_ functions

    main

    Once a request is executed via req_perform(), it returns an <httr2_response> object. You can use the resp_ family of functions to extract information from this object.

    Key functions include:

    • resp_content_type(): Returns the media type of the response.
    • resp_status_desc(): Returns a human-readable description of the HTTP status.
    • resp_body_html(): Parses the response body as HTML.
    resp <- req_perform(req)

resp |> resp_content_type()
resp |> resp_status_desc()
resp |> resp_body_html()

  6. Configure automatic retries with req_retry

    main

    You can define retry policies for your requests using req_retry(). This is useful for handling transient errors or rate limits (e.g., HTTP 429).

    req_retry() allows you to specify:

    • max_tries: The maximum number of attempts.
    • Policies for which errors are considered transient and how long to wait between tries.
    req |> req_retry(max_tries = 5)