---
title: "REST API"
format:
  html:
    code-fold: true
    code-summary: "Show code"
vignette: >
  %\VignetteIndexEntry{REST API}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

```{css, echo=FALSE}
.main-container { max-width: 95vw !important; }
body .container-fluid { max-width: 95vw; }
```

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = ""
)

if (requireNamespace("micromort", quietly = TRUE)) {
  library(micromort)
} else {
  pkgload::load_all(quiet = TRUE)
}

library(targets)
library(DT)

# Shared safe_tar_read with RDS fallback (see inst/vignette_utils.R)
source(file.path(tryCatch(rprojroot::find_root(rprojroot::is_r_package),
  error = function(e) "."), "inst", "vignette_utils.R"))
```

The micromort package includes a full REST API with 30 endpoints for accessing
risk data programmatically. The API is built with [plumber](https://www.rplumber.io/)
and returns JSON with a standard response envelope.

## Getting Started

Launch the API from R:

```r
library(micromort)
launch_api()
#> ── Micromort Data API ──
#> ℹ Starting server at http://127.0.0.1:8080
#> ℹ Swagger docs: http://127.0.0.1:8080/__docs__/
```

The interactive Swagger UI at `/__docs__/` lets you explore all endpoints,
view parameter descriptions, and try requests directly in the browser.

## Response Envelope

Every endpoint returns a standard JSON envelope:

```json
{
  "data": [ ... ],
  "meta": {
    "source": "micromort v0.4.0",
    "endpoint": "/v1/risks/acute",
    "n_rows": 10,
    "timestamp": "2026-03-09T12:00:00Z",
    "params": { "category": "Medical" }
  }
}
```

The `data` field contains the result (array or object). The `meta` field includes
package version, endpoint path, row count, ISO 8601 timestamp, and the query
parameters used.

## Core Risk Data

### Acute risks

Retrieve enriched acute risk data with optional filtering by category,
minimum micromort threshold, and result limit.

```bash
curl "http://localhost:8080/v1/risks/acute?category=Medical&limit=10"
```

```{r acute-sample}
show_target("vig_api_acute_sample")
```

### Chronic risks

Query chronic lifestyle factors that gain or lose microlives per day.

```bash
curl "http://localhost:8080/v1/risks/chronic?direction=gain"
```

```{r chronic-gains}
show_target("vig_api_chronic_gains")
```

### Cancer risks

Cancer mortality by type, sex, and age group with family history multipliers.

```bash
curl "http://localhost:8080/v1/risks/cancer?age_group=All%20ages"
```

```{r cancer-top3}
show_target("vig_api_cancer_top3")
```

## Risk Analysis

### Risk equivalence

Find activities with equivalent risk to a reference activity. The response
includes the ratio (how many of the reference activity equals one of each
comparison activity).

```bash
curl "http://localhost:8080/v1/analysis/equivalence?reference=Chest+X-ray+(radiation+per+scan)"
```

```{r equivalence-sample}
show_target("vig_api_equivalence_sample")
```

### Exchange matrix

Build a cross-comparison matrix for multiple activities. This is a POST
endpoint that accepts a JSON body with an optional `activities` array:

```bash
curl -X POST "http://localhost:8080/v1/analysis/exchange-matrix" \
  -H "Content-Type: application/json" \
  -d '{"activities": ["Skiing", "Scuba diving, trained", "Skydiving (US)"]}'
```

## Unit Conversion

Convert between probability, micromorts, microlives, and loss of life expectancy.

```bash
# Probability to micromorts
curl "http://localhost:8080/v1/convert/to-micromort?prob=0.000001"

# Micromorts to probability
curl "http://localhost:8080/v1/convert/to-probability?micromorts=1"

# Loss of life expectancy (minutes)
curl "http://localhost:8080/v1/convert/lle?prob=0.00001&life_expectancy=40"

# Monetary value of a micromort (default VSL = $10M)
curl "http://localhost:8080/v1/convert/value?vsl=10000000"
```

```{r conversion-table}
show_target("vig_api_conversion_table")
```

## Age-Based Hazard Rates

Calculate daily micromort exposure from background mortality at any age,
using Gompertz-Makeham mortality models.

```bash
curl "http://localhost:8080/v1/convert/hazard-rate?age=50&sex=female"
```

```{r hazard-ages}
show_target("vig_api_hazard_ages")
```

## Full Endpoint Reference

All 30 API endpoints with their HTTP method, path, description, and parameters:

```{r endpoint-summary}
show_target("vig_api_endpoint_summary")
```

## Using from R

You can call the API from R using [httr2](https://httr2.r-lib.org/):

```{r httr2-example, eval=FALSE}
library(httr2)

base_url <- "http://localhost:8080"

# GET request with query parameters
resp <- request(base_url) |>
  req_url_path("/v1/risks/acute") |>
  req_url_query(category = "Sport", limit = 5) |>
  req_perform() |>
  resp_body_json()

# The data lives in resp$data
tibble::as_tibble(do.call(rbind, lapply(resp$data, as.data.frame)))

# POST request with JSON body
resp <- request(base_url) |>
  req_url_path("/v1/analysis/exchange-matrix") |>
  req_body_json(list(
    activities = c("Skiing", "Scuba diving, trained")
  )) |>
  req_perform() |>
  resp_body_json()
```

## Reproducibility

```{r rest_api-session-info, eval=TRUE}
sessionInfo()
```