httpgd API • httpgd

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)