# nectar

An opinionated framework for use within api-wrapping R packages.

## Installation

You can install the development version of nectar from
[GitHub](https://github.com/) with:

``` r
# install.packages("pak")
pak::pak("api2r/nectar")
```

## Usage

nectar provides an opinionated framework for building R packages that
wrap web APIs. The three core functions compose into a natural pipeline:

1.  Prepare a request (attach auth, pagination, and tidy functions)

``` r
req <- req_prepare(
  "https://api.crossref.org/works",
  query = list(
    rows = 10, cursor = "*", select = c("publisher", "DOI"), .multi = "comma"
  ),
  tidy_policy = tidy_policy_json_tibblify(subset_path = c("message", "items")),
  pagination_fn = iterate_with_json_cursor(
    param_name = "cursor",
    next_cursor_path = c("message", "next-cursor")
  )
)
```

2.  Perform the request (handles pagination and retries automatically)

``` r
resps <- req_perform_opinionated(req, max_reqs = 2)
```

3.  Parse all responses into a single tibble

``` r
result <- resp_parse(resps)
result
```

See [`vignette("nectar")`](https://nectar.api2r.org/articles/nectar.md)
for a full walk-through.

## Code of Conduct

Please note that the nectar project is released with a [Contributor Code
of Conduct](https://nectar.api2r.org/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.

# Package index

## All functions

- [`auth_api_key()`](https://nectar.api2r.org/reference/auth_api_key.md)
  : Prepare API key authentication independent of a request
- [`auth_prepare()`](https://nectar.api2r.org/reference/auth_prepare.md)
  : Prepare authentication independent of a request
- [`choose_pagination_fn()`](https://nectar.api2r.org/reference/choose_pagination_fn.md)
  : Extract a pagination policy from a request
- [`compact_nested_list()`](https://nectar.api2r.org/reference/compact_nested_list.md)
  : Discard empty elements
- [`do_if_fn_defined()`](https://nectar.api2r.org/reference/do_if_fn_defined.md)
  : Use a provided function
- [`iterate_with_json_cursor()`](https://nectar.api2r.org/reference/iterate_with_json_cursor.md)
  : Iteration helper for json cursors
- [`req_auth_api_key()`](https://nectar.api2r.org/reference/req_auth_api_key.md)
  : Authenticate with an API key
- [`req_init()`](https://nectar.api2r.org/reference/req_init.md) : Setup
  a basic API request
- [`req_modify()`](https://nectar.api2r.org/reference/req_modify.md) :
  Modify an API request for a particular endpoint
- [`req_pagination_policy()`](https://nectar.api2r.org/reference/req_pagination_policy.md)
  : Define a pagination policy for a request
- [`req_perform_opinionated()`](https://nectar.api2r.org/reference/req_perform_opinionated.md)
  : Perform a request with opinionated defaults
- [`req_pkg_user_agent()`](https://nectar.api2r.org/reference/req_pkg_user_agent.md)
  : Append package information to user agent
- [`req_prepare()`](https://nectar.api2r.org/reference/req_prepare.md) :
  Prepare a request for an API
- [`req_tidy_policy()`](https://nectar.api2r.org/reference/req_tidy_policy.md)
  : Define a tidy policy for a request
- [`resp_body_auto()`](https://nectar.api2r.org/reference/resp_body_auto.md)
  : Automatically choose a body parser
- [`resp_body_csv()`](https://nectar.api2r.org/reference/resp_body_csv.md)
  [`resp_body_tsv()`](https://nectar.api2r.org/reference/resp_body_csv.md)
  : Extract tabular data from response body
- [`resp_body_separate()`](https://nectar.api2r.org/reference/resp_body_separate.md)
  : Extract response body into list
- [`resp_parse()`](https://nectar.api2r.org/reference/resp_parse.md) :
  Parse one or more responses
- [`resp_tidy()`](https://nectar.api2r.org/reference/resp_tidy.md) :
  Extract and clean an API response
- [`resp_tidy_json()`](https://nectar.api2r.org/reference/resp_tidy_json.md)
  : Extract and optionally subset a JSON API response
- [`resp_tidy_json_tibblify()`](https://nectar.api2r.org/reference/resp_tidy_json_tibblify.md)
  : Extract and clean a JSON API response with tibblify
- [`resp_tidy_unknown()`](https://nectar.api2r.org/reference/resp_tidy_unknown.md)
  : Error informatively for unknown response types
- [`tidy_policy_body_auto()`](https://nectar.api2r.org/reference/tidy_policy_body_auto.md)
  : A policy to automatically parse a response body
- [`tidy_policy_json()`](https://nectar.api2r.org/reference/tidy_policy_json.md)
  : A policy to parse a response body as JSON
- [`tidy_policy_json_tibblify()`](https://nectar.api2r.org/reference/tidy_policy_json_tibblify.md)
  : A policy to parse a response body as JSON
- [`tidy_policy_prepare()`](https://nectar.api2r.org/reference/tidy_policy_prepare.md)
  : Prepare tidying independent of a request
- [`tidy_policy_unknown()`](https://nectar.api2r.org/reference/tidy_policy_unknown.md)
  : A policy to error for unknown response bodies
- [`url_normalize()`](https://nectar.api2r.org/reference/url_normalize.md)
  : Normalize a URL
- [`url_path_append()`](https://nectar.api2r.org/reference/url_path_append.md)
  : Add path elements to a URL

# Articles

### All vignettes

- [nectar](https://nectar.api2r.org/articles/nectar.md):