---
title: "httpgd API"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{httpgd API}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
[httpgd](https://github.com/nx10/httpgd/blob/master/README.md) can be accessed both from R and from HTTP/WebSockets.
## 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
While all the APIs can be accessed stateless, the graphics device does have a state defined by.
| Field | Type | Description |
| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `upid` | `int` | Update id. Changes when plots are removed or when something is drawn. |
| `hsize` | `int` | Number of plots in the history. |
| `active` | `bool` | Whether the graphics device is active. When another graphics device is activated, the device will become inactive and not be able to render any plots that are not cached (no resizes). |
To receive state changes as they happen [WebSockets can be used](#from-websockets). Alternatively `/state` may be polled repeatedly.
### From R
```R
unigd::ugd_state()
```
Note: Prior to `httpgd 2.0` this function also returned `host`, `port` and security `token` of the server. These fields are now accessed via `hgd_details()`.
### From HTTP
```
/state
```
| Key | Value | Default |
| ------- | ---------------------------- | ------------------------------------------------------- |
| `token` | [Security token](#security). | (The `X-HTTPGD-TOKEN` header can be set alternatively.) |
Will respond with a JSON object.
### From WebSockets
httpgd accepts WebSocket connections on the same port as the HTTP server. [Server state](#Server-state) changes will be broadcasted immediately to all connected clients in JSON format.
## Get Renderers
httpgd includes multiple renderers that can dynamically render plots to different target formats. As new formats may be added as the development on httpgd continues, and some depend on optional system dependencies, a list of available renderers can be obtained during runtime.
The following is a complete list of renderers.
```{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 in various file formats from both R and HTTP. The actual plot construction in R is relatively slow so httpgd caches the plot in the last requested size. Subsequent calls with the same width and height or without a size specified will always be fast. (This way "flipping" through plot pages is very fast.)
### From R
Example:
```R
unigd::ugd_render(page = 3, width = 800, height = 600) # Get plot at index 3 with 800*600
unigd::ugd_render() # Get last plot with cached size
```
`page` can either be a number to indicate a plot index or a static plot ID (see: hgd_id()).
This function returns the plot as a string. The `file` attribute can be used to save the SVG directly to disk.
### From HTTP
Example:
```
/plot?index=2&width=800&height=600
```
Parameters:
| Key | Value | Default |
| ---------- | ---------------------------- | ------------------------------------------------------- |
| `width` | With 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 that the HTTP API uses 0-based indexing and the R API 1-based indexing. This is done to conform to R and JavaScript on both ends. (This means the the first plot is accessed with `/plot?index=0` and `unigd::ugd_render(page = 1)`.)
## Remove plots
### From R
Examples:
```R
unigd::ugd_remove(page = 2) # Remove the second page
unigd::ugd_clear() # Clear all pages
```
### From HTTP
Examples:
```
/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
The problem with requesting individual plots by index is, that a plots index will change when earlier plots are removed from the plot history.
To circumvent this, each plot also is assigned a static ID.
All APIs that access individual plots can also be called with static IDs instead of indices.
### From R
Examples:
```R
unigd::ugd_id(index = 2) # Static ID of the second plot
unigd::ugd_id() # Static ID of the last plot
```
Note: The `limit` parameter can be adjusted to obtain multiple or all plot IDs.
### From HTTP
Examples:
```
/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.) |
Notes:
- The `limit` parameter can be specified to support pagination.
- The JSON response will contain the [state](#get-state) to allow checking for desynchronisation.
## Security
A security token can be set when starting the device:
```R
hgd(..., token = "secret")
```
When set, each API request has to include this token inside the header `X-HTTPGD-TOKEN` or as a query param `?token=secret`.
`token` is by default set to `TRUE` to generate a random 8 character alphanumeric token. If it is set to a number, a random token of that length will be generated. `FALSE` deactivates the security token.
CORS is off by default but can be enabled on startup:
```R
hgd(..., cors = TRUE)
```