Skip to contents

Initialize a new client package

initialize_client.Rd

Create absent package scaffold files, a local schema copy, project policy, a client-owned httr2 request helper, and session controls.

Usage

initialize_client(root, schema, package = NULL, title = NULL, author = NULL,
    license = NULL, base_url = NULL,
    naming = c("operation_id", "tag_prefix"), group_by = c("tag", "none"),
    name_case = c("asis", "snake_case", "camel_case", "pascal_case",
        "screaming_snake_case", "dot_case"), companions = character())

Arguments

root

Destination client directory; it may be created when absent.

schema

Local JSON, YAML, or YML schema, or a reviewed data frame returned by configure_apis for multiple APIs. Multi-API setup requires an existing root containing those schemas, and a new package. Each included API receives a separate request helper, namespaced function names and credential identities.

package

New R package name, for example catalogueclient. Must agree with an existing DESCRIPTION when supplied.

title

Human-readable package title, required for a new package.

author

Named list with given, family, and email strings, required for a new package.

license

Explicit license string for a new package. MIT + file LICENSE also creates an MIT license metadata file.

base_url

Optional absolute HTTP(S) override for all operations in the new client-owned transport. Overrides schema servers; a runtime option can override it.

naming

Preserve operationId names by default, or propose tag-prefixed snake_case names. See configure_client.

group_by

Group operations by first tag (default), or use one default group with none. Multi-API initialization writes one YAML file per API with nested groups; single-schema initialization keeps flat group files.

companions

Optional selection of batching and/or pagination. Emits reusable, exported, helper-prefixed companions into the client-owned request helper and records their baseline. Empty by default. Pagination adds digest to new-client Imports; an existing DESCRIPTION must declare it.

name_case

Case convention for proposed names. Choices are as-is, snake_case, camelCase, PascalCase, SCREAMING_SNAKE_CASE, and dot.case. See configure_client.

Value

A list of applied file records, each containing file, path, and action. The configuration attribute contains proposed files, operation assignments, and diagnostics. Stops before application for invalid metadata, tag filename collisions, or conflicting scaffold paths.

Details

This function writes immediately and refuses any existing-file conflict. Supply package, title, author (given, family, email), and license for a new package. Existing DESCRIPTION metadata is retained; it must already declare httr2 and jsonlite, which the default transport needs for HTTP and JSON. Adding a new default transport also requires curl for form uploads. Without an explicit override, generated wrappers use operation, path, then root servers, resolving variable defaults. Ambiguous or unsupported selection produces server_diagnostics and fails before HTTP unless a runtime override is supplied. Baseline YAML defaults.request_controls exposes timeout, max_retries, and retry_writes. Regeneration passes these inherited defaults into helper calls without editing the client-owned helper. Runtime options override these fields. The helper reads the lowercase dry-run prefix plus .request as an R option containing base_url, timeout (default 30 seconds per attempt), max_retries (default 0), and retry_writes (default FALSE). Enabled retries cover transient HTTP responses for GET, HEAD, OPTIONS, PUT and DELETE; other methods need explicit write permission. Retry-After is honored. Normal generation never updates this helper. Initialization does not generate wrappers or tests: follow with generate_client(). The helper is client runtime code and does not import specmill.

New clients also receive client-owned R/api_options.R with <package>_run_verbose(verbose = FALSE) and <package>_dry_run(enabled = FALSE). Function prefixes preserve the exact package name; no unprefixed control aliases are exported. These set package-prefixed run_verbose and dry_run R options. Both default to off. An explicit dry-run option overrides the legacy dry-run environment flag. Dry runs return prepared httr2 requests without sending them; input validation and authentication still apply, and returned requests may contain credentials. Verbose messages contain method and HTTP status only. Multi-API clients share one set of controls. Existing helpers and clients require manual adoption; regeneration never overwrites client-owned runtime files.

See also

configure_hooks for optional client-owned pre/post execution. Step-by-step guide.

Note

Service YAML includes explicit operation allowlists and editable names, including unsupported operations. Name collisions and unsupported transports require review before wrapper generation; initialization does not resolve them. Inspect attr(result, 'configuration')$diagnostics, or preview with configure_client() before initialization.