---
title: "07. API Usage"
format:
  html:
    toc: true
    toc-expand: 2
    toc-location: left
    code-fold: true
    code-summary: "Show code"
vignette: >
  %\VignetteIndexEntry{07. API Usage}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
#| echo: false
#| results: asis
in_pkgdown <- nzchar(Sys.getenv("IN_PKGDOWN"))
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = TRUE,
  message = FALSE,
  warning = FALSE,
  fig.width = 8,
  fig.height = 6
)
if (!in_pkgdown) library(targets)

# Shared vignette utilities (safe_tar_read, show_target, render helpers)
utils_path <- system.file("vignette_utils.R", package = "coMMpass")
if (utils_path == "") {
  utils_path <- if (file.exists("../inst/vignette_utils.R")) "../inst/vignette_utils.R"
  else if (file.exists("inst/vignette_utils.R")) "inst/vignette_utils.R"
  else stop("Cannot find vignette_utils.R")
}
source(utils_path, local = TRUE)
```

```{r pkgdown-banner}
#| results: asis
#| eval: !expr in_pkgdown
#| echo: false
cat("::: {.callout-note}\n## Online documentation\nThis vignette displays pre-computed results. Run the targets pipeline locally for interactive analysis.\n:::\n")
```

## Overview

The CoMMpass Analysis project provides pre-computed analysis results as static
JSON files hosted on GitHub Pages. These endpoints are updated on each pipeline
run and serve read-only data derived from the
[GDC portal](https://portal.gdc.cancer.gov/projects/MMRF-COMMPASS).

**Base URL:** `https://JohnGavin.github.io/coMMpass-analysis/api/v1/`

Data is pre-computed via a `targets` pipeline and serialized to JSON. For raw
(non-derived) data, visit the original data sources listed in the
[Raw Data Sources] section below.

## Available Endpoints

The table below lists all JSON API endpoints with their descriptions and record counts.

```{r endpoints-table}
#| echo: false
#| results: asis
show_target("vig_api_endpoints_dt")
```

## Example: curl

Fetch endpoint data from the command line using `curl` and `jq`.

```{r example-curl, results='asis'}
safe_tar_read("code_api_curl")
```

## Example: R (jsonlite)

Load API data directly into R data frames using `jsonlite::fromJSON()`.

```{r example-r, results='asis'}
safe_tar_read("code_api_r")
```

## Example: Python (requests)

Access the API from Python using `requests` and `pandas`.

```{r example-python, results='asis'}
safe_tar_read("code_api_python")
```

## Raw Data Sources

This pipeline uses **open-access GDC data only**. For non-derived data:

- **GDC Data Portal:** <https://portal.gdc.cancer.gov/projects/MMRF-COMMPASS>
- **GDC API:** <https://api.gdc.cancer.gov/>

Additional data (FISH, PFS, treatment response) would require MMRF Researcher
Gateway access (<https://research.themmrf.org/>), which is not currently available
to this project.

## Phase 2 Roadmap

A future release will provide a dynamic [plumber](https://www.rplumber.io/)
API with query parameters for filtering, subsetting, and custom analyses.
The plumber endpoint functions already exist in `R/10_api.R` and
`inst/plumber/plumber.R`. Phase 2 will add authentication, rate limiting,
and OpenAPI documentation.

## Data Sources

Results in this vignette are derived from the
[MMRF CoMMpass study](https://portal.gdc.cancer.gov/projects/MMRF-COMMPASS)
(MMRF-COMMPASS, ~1,143 patients), downloaded via
[TCGAbiolinks](https://bioconductor.org/packages/TCGAbiolinks/).
The pipeline runs with a configurable `sample_limit` (default 200; CI uses 20).

For full citations, data access tiers, and the distinction between
pipeline data and synthetic test data, see the
[Data Sources](data-sources.html) vignette.

## Recent Changes

Recent project commits with lines added, files changed, and change categories.

```{r changelog}
#| echo: false
#| results: asis
show_target("vig_git_changelog")
```

## Reproducibility

<details>
<summary>Session Info (click to expand)</summary>

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

</details>