11-api-reference.Rmd

```{r, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
knitr::opts_chunk$set(eval = FALSE)
```

# API Reference

<div class="info-box">
<strong>Base URL:</strong> <code>https://api.internetofwildlife.com</code>
<br>
<strong>Protocol:</strong> HTTPS
<br>
<strong>Method:</strong> All endpoints use POST
<br>
<strong>Encoding:</strong> JSON
<br>
<strong>Timeout:</strong> 60 seconds per request
</div>

All endpoints require an API token passed in the JSON request body as `token`. The token is loaded from a `.env` file via `dotenv` and accessed with `Sys.getenv("MY_TOKEN")`.

```{r}
library(dotenv)
load_dot_env()
my_token <- Sys.getenv("MY_TOKEN")
```

## Typical Workflow

```
1. Authenticate       load_dot_env() -> Sys.getenv("MY_TOKEN")
2. List projects      POST /station/api/projects
3. List stations      POST /station/api/stations/         (per project)
4. List files         POST /station/api/file-list          (per station, paginated)
5. Download files     POST /station/api/download-file/     (per file)
6. (Optional) Import  file_handle() -> db_prep() -> db_insert()
```

The `get_my_data()` function orchestrates this entire workflow in a single call.

## POST Wrapper

All endpoints (except direct calls in `get_my_projects` and `project_list`) go through the `post()` function in `R/post.R`:

```{r}
post(endpoint, payload = NULL, show_progress = FALSE)
```

* Automatically injects `token = my_token` into every request
* 60-second timeout on all requests
* Detects HTTP 503 and emits a warning suggesting narrower date ranges or pagination
* Calls `httr::stop_for_status()` to raise on other HTTP errors
* Optional progress bar via `httr::progress()`

<hr class="section-divider">

## List Projects <span class="tag-label tag-projects">Projects</span>

<div class="endpoint-header">
<span class="method-badge method-post">POST</span>
<span class="endpoint-path">/station/api/projects</span>
</div>

Retrieves all projects associated with the authenticated user's account.

### Parameters

<table class="param-table">
<thead>
<tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
  <td><code>token</code></td>
  <td><span class="param-type">string</span></td>
  <td><span class="param-required">REQUIRED</span></td>
  <td>API authentication token</td>
</tr>
</tbody>
</table>

### curl Example

```{bash}
curl -X POST https://api.internetofwildlife.com/station/api/projects \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN"}'
```

### Response

<div class="response-section">

**200 OK**

```json
{
  "projects": [
    {
      "id": "abc123",
      "name": "My Wildlife Project"
    },
    {
      "id": "def456",
      "name": "Raptor Tracking Study"
    }
  ]
}
```

</div>

### Errors

<table class="error-table">
<thead>
<tr><th>Status</th><th>Cause</th><th>What You See</th></tr>
</thead>
<tbody>
<tr>
  <td><span class="error-code">401</span></td>
  <td>Invalid or expired API token</td>
  <td><code>httr::stop_for_status()</code> raises: <code>"Unauthorized (HTTP 401)"</code></td>
</tr>
<tr>
  <td><span class="error-code">503</span></td>
  <td>Server overloaded or temporarily down</td>
  <td>Warning: <code>"Server query timeout — try narrowing your date range or using pagination"</code>, then execution stops</td>
</tr>
<tr>
  <td><span class="error-code">Timeout</span></td>
  <td>Network issue or server unreachable</td>
  <td>R error: <code>"Timeout was reached"</code> after 60 seconds</td>
</tr>
<tr>
  <td><span class="error-code">Empty token</span></td>
  <td><code>.env</code> file missing or <code>MY_TOKEN</code> not set</td>
  <td>API returns auth error; <code>Sys.getenv("MY_TOKEN")</code> silently returns <code>""</code> if unset</td>
</tr>
<tr>
  <td><span class="error-code">Not found</span></td>
  <td>Specified <code>myproject</code> name doesn't match any project</td>
  <td><code>"The project you entered is not found in your project list. Check your spelling and if you have access to the project."</code></td>
</tr>
</tbody>
</table>

### R Package Functions

<div class="used-by">

* <code>get_my_projects()</code> in <code>R/get_my_projects.R</code> — returns a character vector of project names
* <code>project_list()</code> in <code>R/project_list.R</code> — returns filtered project list with optional name matching

</div>

<hr class="section-divider">

## List Stations <span class="tag-label tag-stations">Stations</span>

<div class="endpoint-header">
<span class="method-badge method-post">POST</span>
<span class="endpoint-path">/station/api/stations/</span>
</div>

Retrieves all sensor stations deployed under a given project.

### Parameters

<table class="param-table">
<thead>
<tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
  <td><code>token</code></td>
  <td><span class="param-type">string</span></td>
  <td><span class="param-required">REQUIRED</span></td>
  <td>API authentication token</td>
</tr>
<tr>
  <td><code>project-id</code></td>
  <td><span class="param-type">string</span></td>
  <td><span class="param-required">REQUIRED</span></td>
  <td>Project identifier obtained from the List Projects endpoint</td>
</tr>
</tbody>
</table>

### curl Example

```{bash}
curl -X POST https://api.internetofwildlife.com/station/api/stations/ \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN", "project-id": "YOUR_PROJECT_ID"}'
```

### Response

<div class="response-section">

**200 OK**

```json
{
  "stations": [
    {
      "station": {
        "id": "STATION-001"
      },
      "deploy-at": "2024-01-15T00:00:00.000Z",
      "end-at": "2024-06-01T00:00:00.000Z"
    },
    {
      "station": {
        "id": "STATION-002"
      },
      "deploy-at": "2024-03-01T00:00:00.000Z",
      "end-at": null
    }
  ]
}
```

Each station entry includes:

* **`station.id`** — unique station identifier
* **`deploy-at`** — ISO 8601 deployment start timestamp
* **`end-at`** — ISO 8601 deployment end timestamp (null for active stations)

</div>

### Errors

<table class="error-table">
<thead>
<tr><th>Status</th><th>Cause</th><th>What You See</th></tr>
</thead>
<tbody>
<tr>
  <td><span class="error-code">401</span></td>
  <td>Invalid or expired API token</td>
  <td><code>httr::stop_for_status()</code> raises: <code>"Unauthorized (HTTP 401)"</code></td>
</tr>
<tr>
  <td><span class="error-code">404</span></td>
  <td><code>project-id</code> does not exist or user lacks access</td>
  <td><code>httr::stop_for_status()</code> stops execution with an HTTP error</td>
</tr>
<tr>
  <td><span class="error-code">503</span></td>
  <td>Server overloaded or temporarily down</td>
  <td>Warning: <code>"Server query timeout — try narrowing your date range or using pagination"</code>, then execution stops</td>
</tr>
<tr>
  <td><span class="error-code">Timeout</span></td>
  <td>Network issue or server unreachable</td>
  <td>R error: <code>"Timeout was reached"</code> after 60 seconds</td>
</tr>
<tr>
  <td><span class="error-code">Empty list</span></td>
  <td>Project exists but has no deployed stations</td>
  <td>Response returns <code>"stations": []</code>; downstream code in <code>get_data()</code> skips processing</td>
</tr>
</tbody>
</table>

### R Package Functions

<div class="used-by">

* <code>get_stations()</code> in <code>R/get_stations.R</code>
* <code>get_data()</code> in <code>R/get_data.R</code> — iterates stations to build file lists

</div>

<hr class="section-divider">

## List Station Files <span class="tag-label tag-files">Files</span>

<div class="endpoint-header">
<span class="method-badge method-post">POST</span>
<span class="endpoint-path">/station/api/file-list</span>
</div>

Retrieves metadata for data files available from a specific station, with optional date range and file type filtering. Supports pagination via `limit` and `offset`.

### Parameters

<table class="param-table">
<thead>
<tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
  <td><code>token</code></td>
  <td><span class="param-type">string</span></td>
  <td><span class="param-required">REQUIRED</span></td>
  <td>API authentication token</td>
</tr>
<tr>
  <td><code>station-id</code></td>
  <td><span class="param-type">string</span></td>
  <td><span class="param-required">REQUIRED</span></td>
  <td>Station identifier obtained from the List Stations endpoint</td>
</tr>
<tr>
  <td><code>begin</code></td>
  <td><span class="param-type">date</span></td>
  <td><span class="param-required">REQUIRED</span></td>
  <td>Start date for file search (ISO date format, e.g. <code>2024-01-01</code>)</td>
</tr>
<tr>
  <td><code>end</code></td>
  <td><span class="param-type">date</span></td>
  <td><span class="param-optional">optional</span></td>
  <td>End date for file search. Defaults to today if omitted.</td>
</tr>
<tr>
  <td><code>file-types</code></td>
  <td><span class="param-type">string[]</span></td>
  <td><span class="param-optional">optional</span></td>
  <td>Filter by file types: <code>data</code>, <code>node-data</code>, <code>gps</code>, <code>log</code>, <code>telemetry</code>, <code>sensorgnome</code>, <code>ble</code>, <code>blu</code></td>
</tr>
<tr>
  <td><code>limit</code></td>
  <td><span class="param-type">integer</span></td>
  <td><span class="param-optional">optional</span></td>
  <td>Maximum number of files to return (for pagination)</td>
</tr>
<tr>
  <td><code>offset</code></td>
  <td><span class="param-type">integer</span></td>
  <td><span class="param-optional">optional</span></td>
  <td>Number of files to skip (for pagination)</td>
</tr>
</tbody>
</table>

### curl Examples

**Basic request (required fields only):**

```{bash}
curl -X POST https://api.internetofwildlife.com/station/api/file-list \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN", "station-id": "YOUR_STATION_ID", "begin": "2024-01-01"}'
```

**Full request with all options:**

```{bash}
curl -X POST https://api.internetofwildlife.com/station/api/file-list \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "station-id": "YOUR_STATION_ID",
    "begin": "2024-01-01",
    "end": "2024-02-01",
    "file-types": ["data", "gps"],
    "limit": 100,
    "offset": 0
  }'
```

### Response

<div class="response-section">

**200 OK**

```json
{
  "files": [
    {
      "id": "file-789",
      "name": "CTT-STATION001-data.csv.gz"
    },
    {
      "id": "file-790",
      "name": "CTT-STATION001-gps.csv.gz"
    }
  ]
}
```

</div>

<div class="info-box">
<strong>Note:</strong> Large date ranges may cause 503 server timeouts. Use <code>get_station_file_list_paginated()</code> to handle this automatically. The paginated version retries failed chunks up to <code>max_retries</code> times (default 3) with exponential backoff (2s, 4s, 6s).
</div>

### Errors

<table class="error-table">
<thead>
<tr><th>Status</th><th>Cause</th><th>What You See</th></tr>
</thead>
<tbody>
<tr>
  <td><span class="error-code">401</span></td>
  <td>Invalid or expired API token</td>
  <td><code>httr::stop_for_status()</code> raises: <code>"Unauthorized (HTTP 401)"</code></td>
</tr>
<tr>
  <td><span class="error-code">503</span></td>
  <td>Date range too large; server times out</td>
  <td>Warning: <code>"Server query timeout — try narrowing your date range or using pagination"</code>. The paginated wrapper catches this and retries: <code>"Request timed out, retrying (attempt X of Y)..."</code></td>
</tr>
<tr>
  <td><span class="error-code">Timeout</span></td>
  <td>Network issue or server unreachable</td>
  <td>R error: <code>"Timeout was reached"</code> after 60 seconds. Paginated wrapper retries up to <code>max_retries</code> times with exponential backoff.</td>
</tr>
<tr>
  <td><span class="error-code">Invalid type</span></td>
  <td>A value in <code>file-types</code> is not one of the 8 valid types</td>
  <td>Warning: <code>"WARNING: invalid file type specified - ignoring: &lt;type&gt;"</code>. Invalid types are dropped; request proceeds with valid types only.</td>
</tr>
<tr>
  <td><span class="error-code">404</span></td>
  <td><code>station-id</code> does not exist</td>
  <td><code>httr::stop_for_status()</code> stops execution with an HTTP error</td>
</tr>
<tr>
  <td><span class="error-code">Empty result</span></td>
  <td>Station has no files for the given date range</td>
  <td><code>get_data()</code> prints <code>"no files found from API"</code> and returns an empty list</td>
</tr>
<tr>
  <td><span class="error-code">Max retries</span></td>
  <td>Paginated wrapper exhausts all retry attempts on a chunk</td>
  <td>The original error is re-thrown via <code>stop(e)</code>, halting execution</td>
</tr>
</tbody>
</table>

### R Package Functions

<div class="used-by">

* <code>get_station_file_list()</code> in <code>R/get_station_file_list.R</code> — single request with optional pagination params
* <code>get_station_file_list_paginated()</code> in <code>R/get_station_file_list_paginated.R</code> — automatic date-chunked pagination with retry logic

</div>

<hr class="section-divider">

## Download File <span class="tag-label tag-files">Files</span>

<div class="endpoint-header">
<span class="method-badge method-post">POST</span>
<span class="endpoint-path">/station/api/download-file/</span>
</div>

Downloads the contents of a single data file by its ID.

### Parameters

<table class="param-table">
<thead>
<tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
  <td><code>token</code></td>
  <td><span class="param-type">string</span></td>
  <td><span class="param-required">REQUIRED</span></td>
  <td>API authentication token</td>
</tr>
<tr>
  <td><code>file-id</code></td>
  <td><span class="param-type">string</span></td>
  <td><span class="param-required">REQUIRED</span></td>
  <td>File identifier obtained from the List Station Files endpoint</td>
</tr>
<tr>
  <td><code>bypass-encoding</code></td>
  <td><span class="param-type">string</span></td>
  <td><span class="param-optional">optional</span></td>
  <td>Set to <code>"plain"</code> to bypass encoding. Used automatically as a fallback on retry.</td>
</tr>
</tbody>
</table>

### curl Examples

**Basic download:**

```{bash}
curl -X POST https://api.internetofwildlife.com/station/api/download-file/ \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN", "file-id": "YOUR_FILE_ID"}'
```

**With bypass encoding (fallback on error):**

```{bash}
curl -X POST https://api.internetofwildlife.com/station/api/download-file/ \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_API_TOKEN", "file-id": "YOUR_FILE_ID", "bypass-encoding": "plain"}'
```

### Response

<div class="response-section">

**200 OK** — Raw file content (CSV text, UTF-8 encoded)

```
TagId,NodeId,TagRSSI,Validated,Time
TAG-001,NODE-A,-70,1,2024-01-15 12:00:00
TAG-001,NODE-B,-85,1,2024-01-15 12:00:00
```

In batch downloads via `get_data()`, each file result is tracked in a dataframe. The final summary prints: `"Download complete: X succeeded, Y failed out of Z files"`

</div>

### Errors

<table class="error-table">
<thead>
<tr><th>Status</th><th>Cause</th><th>What You See</th></tr>
</thead>
<tbody>
<tr>
  <td><span class="error-code">401</span></td>
  <td>Invalid or expired API token</td>
  <td><code>httr::stop_for_status()</code> raises: <code>"Unauthorized (HTTP 401)"</code></td>
</tr>
<tr>
  <td><span class="error-code">404</span></td>
  <td><code>file-id</code> does not match any file on the server</td>
  <td><code>httr::stop_for_status()</code> stops execution with an HTTP error</td>
</tr>
<tr>
  <td><span class="error-code">500</span></td>
  <td>File content has encoding issues the server can't handle</td>
  <td><code>download_files()</code> prints <code>"Here's the original error message:"</code> followed by the error detail, then automatically retries with <code>bypass-encoding = "plain"</code></td>
</tr>
<tr>
  <td><span class="error-code">500 (retry)</span></td>
  <td>File is corrupted or unrecoverable (retry also fails)</td>
  <td>Error propagates up; <code>get_data()</code> catches it per-file and records <code>status = "failed"</code> in results dataframe</td>
</tr>
<tr>
  <td><span class="error-code">503</span></td>
  <td>Server overloaded or temporarily down</td>
  <td>Warning: <code>"Server query timeout — try narrowing your date range or using pagination"</code>, then execution stops</td>
</tr>
<tr>
  <td><span class="error-code">Timeout</span></td>
  <td>Network issue or server unreachable</td>
  <td>R error: <code>"Timeout was reached"</code> after 60 seconds</td>
</tr>
<tr>
  <td><span class="error-code">Batch failure</span></td>
  <td>Any error during a single file download within <code>get_data()</code></td>
  <td>File is marked <code>"failed"</code> in the results dataframe; remaining files continue. Final summary: <code>"Download complete: X succeeded, Y failed out of Z files"</code></td>
</tr>
</tbody>
</table>

### R Package Functions

<div class="used-by">

* <code>download_files()</code> in <code>R/download_files.R</code>
* Called from <code>get_data()</code> in <code>R/get_data.R</code> for each file in the download queue

</div>