# httpgd API

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()` | `/state` | Get current server state.
`ugd_renderers()` | `/renderers` | Get list of available renderers.
`ugd_render()` | `/plot` | Get rendered plot (any format).
`ugd_clear()` | `/clear` | Remove all plots.
`ugd_remove()` | `/remove` | Remove a single plot.
`ugd_id()` | `/plots` | 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, or by polling `/state`.

### From 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. | (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.

ID | Mime-Type | Renderer | Format
--- | --- | --- | ---
`eps` | `application/postscript` | Encapsulated PostScript (EPS). | Text
`json` | `application/json` | Plot data serialized to JSON format. | Text
`meta` | `application/json` | Plot meta information. | Text
`pdf` | `application/pdf` | Adobe Portable Document Format (PDF). | Binary
`png` | `image/png` | Portable Network Graphics (PNG). | Binary
`png-base64` | `text/plain` | Base64 encoded Portable Network Graphics (PNG). | Text
`ps` | `application/postscript` | PostScript (PS). | Text
`strings` | `text/plain` | List of strings contained in plot. | Text
`svg` | `image/svg+xml` | Scalable Vector Graphics (SVG). | Text
`svgp` | `image/svg+xml` | Version of the SVG renderer that produces portable SVGs. | Text
`svgz` | `image/svg+xml` | Compressed Scalable Vector Graphics (SVGZ). | Binary
`svgzp` | `image/svg+xml` | Version of the SVG renderer that produces portable SVGZs. | Binary
`tiff` | `image/tiff` | Tagged Image File Format (TIFF). | Binary
`tikz` | `text/plain` | LaTeX TikZ code. | Text

### From R

    unigd::ugd_renderers()

Returns a data frame.

### From HTTP

    /renderers

Key | Value | Default
--- | --- | ---
`token` | Security token. | (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

    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. | (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

    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. | (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

    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. | (The `X-HTTPGD-TOKEN` header can be set alternatively.)

The `limit` parameter supports pagination. The JSON response includes the current 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=...`).

    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:

    hgd(cors = TRUE)