This is a centralized template function used by nearly all ct_* functions
to perform API requests. it handles normalization, batching, authentication,
error handling, and data tidying.
Usage
generic_request(
query = NULL,
endpoint,
method = "POST",
server = "ctx_burl",
batch_limit = NULL,
auth = TRUE,
tidy = TRUE,
path_params = NULL,
content_type = "application/json",
body_type = "json",
body = NULL,
query_params = NULL,
paginate = FALSE,
max_pages = 100,
pagination_strategy = NULL,
pagination_cursor_location = NULL,
...
)Arguments
- query
A character vector or list of items to be queried (e.g., DTXSIDs, CASRNs). For static endpoints (batch_limit=0), pass NULL or a placeholder value.
- endpoint
The API endpoint path (e.g., "hazard", "chemical/fate").
- method
The HTTP method to use: "POST" (default for bulk searches) or "GET".
- server
Either a Global environment variable name (e.g., 'ctx_burl') or a direct URL string.
- batch_limit
The number of items to send per request. Bulk POSTs usually use 100-1000. If set to 1, GET requests will append the query item directly to the URL path. If set to 0, treats as static endpoint (no query appending).
- auth
Boolean; whether to include the API key header. Defaults to TRUE.
- tidy
Boolean; whether to convert the result to a tidy tibble. Defaults to TRUE. If FALSE, returns a cleaned list structure.
- path_params
Optional vector or list of additional path parameters to append to the endpoint URL. Used for endpoints with multiple path parameters (e.g., property range searches). These are appended after the primary query parameter in the order provided. Cannot be used with batching (batch_limit > 1).
- content_type
Expected response content type. Defaults to "application/json". Supported types:
"application/json": Parses response as JSON (default behavior)
"text/plain": Returns response as character string
"text/csv" or "text/tab-separated-values": Parses the delimited response as a data frame
"image/*" (e.g., "image/png", "image/svg+xml"): Returns raw bytes or magick image
- body_type
How to encode the request body for POST requests. Defaults to "json". Supported types:
"json": Send as JSON array via
httr2::req_body_json()(default)"raw_text": Send as newline-delimited plain text via
httr2::req_body_raw()with content type "text/plain". Used for endpoints like /chemical/search/equal/.
- body
Optional explicit POST body. When supplied, this value is JSON-encoded instead of the batched
querypayload.- query_params
Optional named list of URL query parameters. Use this for API parameters whose names collide with
generic_request()formals.- paginate
Boolean; whether to automatically fetch all pages for paginated endpoints. Defaults to FALSE. When TRUE, uses httr2::req_perform_iterative() to loop through pages until exhausted or max_pages is reached. Requires pagination_strategy to be set.
- max_pages
Maximum number of pages to fetch when paginate=TRUE. Defaults to 100. Acts as a safety limit to prevent runaway pagination loops.
- pagination_strategy
The pagination strategy to use. One of: "offset_limit", "page_number", "page_size", "cursor", or NULL. When NULL, paginate is ignored. Usually set by generated stubs from Phase 19 metadata.
- pagination_cursor_location
For cursor pagination, the schema-derived cursor location: "query" or "body". Defaults to "query".
- ...
Additional parameters:
If method is "POST": Added as query parameters to the URL.
If method is "GET" and batch_limit is 1: Named arguments are added as query parameters.
If method is "GET" and batch_limit > 1: Added as query parameters to the URL.