---
title: "httpgd API"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{httpgd API}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
httpgd provides an R API and an HTTP/WebSocket API.
## Overview
| R | HTTP | Description |
| ----------------------------------- | ------------------------------ | ----------------------------------- |
| `hgd()` | | Initialize device and start server. |
| `hgd_close()` | | Helper: Close device. |
| `hgd_url()` | | Helper: URL generation. |
| `hgd_browse()` | | Helper: Open browser. |
| [`ugd_state()`](#get-state) | [`/state`](#get-state) | Get current server state. |
| [`ugd_renderers()`](#get-renderers) | [`/renderers`](#get-renderers) | Get list of available renderers. |
| [`ugd_render()`](#render-plot) | [`/plot`](#render-plot) | Get rendered plot (any format). |
| [`ugd_clear()`](#remove-plots) | [`/clear`](#remove-plots) | Remove all plots. |
| [`ugd_remove()`](#remove-plots) | [`/remove`](#remove-plots) | Remove a single plot. |
| [`ugd_id()`](#get-static-ids) | [`/plots`](#get-static-ids) | Get static plot IDs. |
| | `/live` | Live server page. |
## Get state
The device state is defined by:
| Field | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `upid` | `int` | Update ID. Changes when plots are added or removed. |
| `hsize` | `int` | Number of plots in the history. |
| `active` | `bool` | Whether the device is currently active. Inactive devices cannot render uncached plots (e.g. at new sizes). |
State changes can be received in real time via [WebSockets](#from-websockets), or by polling `/state`.
### From R
```R
unigd::ugd_state()
```
Server connection details (`host`, `port`, `token`) are accessed separately via `hgd_details()`.
### From HTTP
```
/state
```
| Key | Value | Default |
| ------- | ---------------------------- | ------------------------------------------------------- |
| `token` | [Security token](#security). | (The `X-HTTPGD-TOKEN` header can be set alternatively.) |
### From WebSockets
httpgd accepts WebSocket connections on the same port as the HTTP server. State changes are broadcast to all connected clients as JSON.
## Get Renderers
httpgd can render plots to multiple formats. Available renderers depend on system dependencies and can be queried at runtime.
```{r echo=FALSE}
df <- unigd::ugd_renderers()
df <- df[order(df$id), ]
knitr::kable(data.frame(
sprintf("`%s`", df$id),
sprintf("`%s`", df$mime),
df$descr,
ifelse(df$text, "Text", "Binary")
), col.names = c("ID", "Mime-Type", "Renderer", "Format"))
```
### From R
```R
unigd::ugd_renderers()
```
Returns a data frame.
### From HTTP
```
/renderers
```
| Key | Value | Default |
| ------- | ---------------------------- | ------------------------------------------------------- |
| `token` | [Security token](#security). | (The `X-HTTPGD-TOKEN` header can be set alternatively.) |
## Render plot
Plots can be rendered from both R and HTTP. httpgd caches the plot at the last requested size, so repeated calls with the same dimensions are fast.
### From R
```R
unigd::ugd_render(page = 3, width = 800, height = 600)
unigd::ugd_render() # last plot, cached size
```
`page` accepts a plot index or a static plot ID (see `ugd_id()`). Returns the plot as a string; use the `file` parameter to save directly to disk.
### From HTTP
```
/plot?index=2&width=800&height=600
```
| Key | Value | Default |
| ---------- | ---------------------------- | ------------------------------------------------------- |
| `width` | Width in pixels. | Last rendered width. (Initially device width.) |
| `height` | Height in pixels. | Last rendered height. (Initially device height.) |
| `zoom` | Zoom level. | `1` (No zoom). `0.5` would be 50% and `2` 200%. |
| `index` | Plot history index. | Newest plot. |
| `id` | Static plot ID. | `index` will be used. |
| `renderer` | Renderer. | `svg`. |
| `token` | [Security token](#security). | (The `X-HTTPGD-TOKEN` header can be set alternatively.) |
**Note:** The HTTP API uses 0-based indexing, the R API uses 1-based indexing. The first plot is `/plot?index=0` in HTTP and `ugd_render(page = 1)` in R.
## Remove plots
### From R
```R
unigd::ugd_remove(page = 2)
unigd::ugd_clear()
```
### From HTTP
```
/remove?index=2
/clear
```
| Key | Value | Default |
| ------- | ---------------------------- | ------------------------------------------------------- |
| `index` | Plot history index. | Newest plot. |
| `id` | Static plot ID. | `index` will be used. |
| `token` | [Security token](#security). | (The `X-HTTPGD-TOKEN` header can be set alternatively.) |
## Get static IDs
Plot indices shift when earlier plots are removed. Each plot is also assigned a static ID that remains stable. All APIs that access individual plots accept static IDs as an alternative to indices.
### From R
```R
unigd::ugd_id(index = 2)
unigd::ugd_id()
```
Use the `limit` parameter to obtain multiple plot IDs at once.
### From HTTP
```
/plots?index=2
/plots
```
| Key | Value | Default |
| ------- | ------------------------------ | ------------------------------------------------------- |
| `index` | Plot history index. | Newest plot. |
| `limit` | Number of subsequent plot IDs. | 1 |
| `token` | [Security token](#security). | (The `X-HTTPGD-TOKEN` header can be set alternatively.) |
The `limit` parameter supports pagination. The JSON response includes the current [state](#get-state) for synchronization checks.
## Security
By default, `hgd()` generates a random 8-character alphanumeric token. Every API request must include this token as a header (`X-HTTPGD-TOKEN`) or query parameter (`?token=...`).
```R
hgd(token = "secret") # fixed token
hgd(token = 16) # random token of length 16
hgd(token = FALSE) # disable token
```
CORS is off by default but can be enabled:
```R
hgd(cors = TRUE)
```