Build a result envelope — envelope • biohttp

The single return shape for the whole package. ok is derived from status rather than passed in, so the two can never disagree.

Usage

envelope(
  status,
  data = NULL,
  source = "API",
  http = NA_integer_,
  error = NULL,
  detail = NULL
)

Arguments

status: One of STATUS_LEVELS.
data: The parsed body on success, NULL otherwise.
source: A friendly label for the service, used in the user-facing message. For example "gnomAD".
http: The HTTP status code, or NA_integer_ when no response arrived.
error: One sentence fit to show a user. Never carries technical detail.
detail: The technical cause, for a log. Never shown to a user.

Value

A list with ok, status, http, data, source, error, detail, and ts.

Details

A client that only wants the parsed body can use body_or_null() instead of reading the fields directly.

Examples

envelope("ok", data = list(symbol = "BRCA1"), source = "MyGene", http = 200L)
#> $ok
#> [1] TRUE
#> 
#> $status
#> [1] "ok"
#> 
#> $http
#> [1] 200
#> 
#> $data
#> $data$symbol
#> [1] "BRCA1"
#> 
#> 
#> $source
#> [1] "MyGene"
#> 
#> $error
#> NULL
#> 
#> $detail
#> NULL
#> 
#> $ts
#> [1] "2026-08-01 08:56:23 UTC"
#> 
envelope("error", source = "gnomAD", http = 503L)
#> $ok
#> [1] FALSE
#> 
#> $status
#> [1] "error"
#> 
#> $http
#> [1] 503
#> 
#> $data
#> NULL
#> 
#> $source
#> [1] "gnomAD"
#> 
#> $error
#> NULL
#> 
#> $detail
#> NULL
#> 
#> $ts
#> [1] "2026-08-01 08:56:23 UTC"
#>