`rest` API reference

An ergonomic REST layer over the http client and json. Hold a value-semantic Client (base URL + default headers + an http.Options request policy) and call JSON-aware verbs; the module handles base-URL joining, query strings, Content-Type, and Bearer / Basic auth headers. It is pure composition - no sockets, no parsing of its own - so all the transport lives in http (which uses net), and this module needs the default jennifer binary. A 4xx / 5xx is a normal Response (inspect .status), not a crash. Build a client with rest.client; layer on TLS (rest.withCA / rest.insecure), a per-request timeout (rest.withTimeout), redirect-following (rest.withRedirects), and retries (rest.withRetries) - each inherited from http.send. For paginated collections, rest.paginate (Link header) and rest.paginateCursor (cursor field) walk every page.

Import with import "rest.j" as rest;. See the rest guide for prose and examples.

Functions

`rest.basic(user as string, pass as string)`

Build an Authorization value for HTTP Basic auth (base64 of "user:password").

Parameters

user {string} - the username
pass {string} - the password

Returns {string} - the "Basic <base64>" header value

`rest.bearer(token as string)`

Build an Authorization value for a Bearer token.

Parameters

token {string} - the bearer token

Returns {string} - the "Bearer <token>" header value

`rest.client(baseUrl as string)`

Build a Client for a base URL, with no default headers and full TLS verification. Layer auth / headers on with withHeader and TLS relaxation with withCA / insecure.

Parameters

baseUrl {string} - the base URL every path joins onto

Returns {Client} - a new client

`rest.delete(c as Client, path as string, query as map of string to string)`

Issue a DELETE with an optional query map.

Parameters

c {Client} - the client
path {string} - the request path, joined onto the base URL
query {map of string to string} - query parameters ({} for none)

Returns {Response} - the response

`rest.get(c as Client, path as string, query as map of string to string)`

Issue a GET with an optional query map ({} for none).

Parameters

c {Client} - the client
path {string} - the request path, joined onto the base URL
query {map of string to string} - query parameters ({} for none)

Returns {Response} - the response

`rest.getJson(c as Client, path as string, query as map of string to string)`

Issue a GET and decode the response body as JSON.

Parameters

c {Client} - the client
path {string} - the request path, joined onto the base URL
query {map of string to string} - query parameters ({} for none)

Returns {json.Value} - the decoded response body

`rest.insecure(c as Client)`

Return a copy of the client that skips TLS certificate verification for every https:// request. This disables server authentication and exposes the connection to a man-in-the-middle - use only for a trusted LAN endpoint you cannot give a proper CA; prefer withCA.

Parameters

c {Client} - the client to copy

Returns {Client} - a new client that accepts any certificate

`rest.paginate(c as Client, path as string, query as map of string to string, maxPages as int)`

Walk a Link-header paginated collection (GitHub / GitLab style), following each response's Link: <url>; rel="next" until it is absent or maxPages is reached, and return the list of decoded page bodies. The first request uses path + query; each next URL is followed verbatim (it carries its own query). maxPages bounds the walk so a mis-behaving server cannot loop forever.

Parameters

c {Client} - the client
path {string} - the first page's path, joined onto the base URL
query {map of string to string} - query parameters for the first page ({} for none)
maxPages {int} - the maximum number of pages to fetch

Returns {list of json.Value} - the decoded body of each page, in order

Throws

{Error} - kind "rest" on a non-2xx page

`rest.paginateCursor(c as Client, path as string, query as map of string to string, cursorPointer as string, cursorParam as string, maxPages as int)`

Walk a cursor paginated collection: fetch a page, read the next cursor from the response body at cursorPointer (a JSON Pointer, e.g. "/meta/next_cursor"), and re-request with that cursor set as the cursorParam query parameter, until the cursor is absent / null / empty or maxPages is reached. Returns the list of decoded page bodies. The cursor may be a JSON string or integer.

Parameters

c {Client} - the client
path {string} - the collection path, joined onto the base URL
query {map of string to string} - the initial query parameters ({} for none)
cursorPointer {string} - a JSON Pointer to the next cursor in each page body
cursorParam {string} - the query-parameter name to send the cursor as
maxPages {int} - the maximum number of pages to fetch

Returns {list of json.Value} - the decoded body of each page, in order

Throws

{Error} - kind "rest" on a non-2xx page

`rest.patch(c as Client, path as string, contentType as string, body as string)`

Issue a PATCH with a content type and body.

Parameters

c {Client} - the client
path {string} - the request path, joined onto the base URL
contentType {string} - the Content-Type header value
body {string} - the request body

Returns {Response} - the response

`rest.patchJson(c as Client, path as string, body as json.Value)`

Issue a PATCH with a JSON body.

Parameters

c {Client} - the client
path {string} - the request path, joined onto the base URL
body {json.Value} - the JSON request body

Returns {Response} - the response

`rest.post(c as Client, path as string, contentType as string, body as string)`

Issue a POST with a content type and body.

Parameters

c {Client} - the client
path {string} - the request path, joined onto the base URL
contentType {string} - the Content-Type header value
body {string} - the request body

Returns {Response} - the response

`rest.postJson(c as Client, path as string, body as json.Value)`

Issue a POST with a JSON body; returns the Response (inspect status).

Parameters

c {Client} - the client
path {string} - the request path, joined onto the base URL
body {json.Value} - the JSON request body

Returns {Response} - the response

`rest.put(c as Client, path as string, contentType as string, body as string)`

Issue a PUT with a content type and body.

Parameters

c {Client} - the client
path {string} - the request path, joined onto the base URL
contentType {string} - the Content-Type header value
body {string} - the request body

Returns {Response} - the response

`rest.putJson(c as Client, path as string, body as json.Value)`

Issue a PUT with a JSON body.

Parameters

c {Client} - the client
path {string} - the request path, joined onto the base URL
body {json.Value} - the JSON request body

Returns {Response} - the response

`rest.withBackoff(c as Client, backoffMs as int)`

Return a copy of the client with a base retry backoff in milliseconds (doubled each attempt; 0 = the 250ms default). Pairs with rest.withRetries.

Parameters

c {Client} - the client to copy
backoffMs {int} - the base backoff in milliseconds

Returns {Client} - a new client with the backoff set

`rest.withCA(c as Client, pem as bytes)`

Return a copy of the client that trusts a private-CA / self-signed PEM certificate (in addition to the system roots) for every https:// request. The safer alternative to insecure: the server is still authenticated.

Parameters

c {Client} - the client to copy
pem {bytes} - a PEM certificate to trust

Returns {Client} - a new client pinned to the CA

`rest.withHeader(c as Client, name as string, value as string)`

Return a copy of the client with one default header set.

Parameters

c {Client} - the client to copy
name {string} - the header name
value {string} - the header value

Returns {Client} - a new client with the header set

`rest.withRedirects(c as Client, maxRedirects as int)`

Return a copy of the client that follows up to maxRedirects 3xx redirects (0 = none; the 3xx is returned as-is). Inherits http.send's redirect rules.

Parameters

c {Client} - the client to copy
maxRedirects {int} - the redirect hop limit

Returns {Client} - a new client that follows redirects

`rest.withRetries(c as Client, maxRetries as int)`

Return a copy of the client that retries a 429 / 5xx up to maxRetries times with exponential backoff (honouring a numeric Retry-After). Use rest.withBackoff for a non-default base backoff.

Parameters

c {Client} - the client to copy
maxRetries {int} - the retry limit

Returns {Client} - a new client that retries

`rest.withTimeout(c as Client, timeoutMs as int)`

Return a copy of the client with a per-request idle timeout (milliseconds; 0 = the 30s default). Bounds each read, so a hung server fails rather than blocking.

Parameters

c {Client} - the client to copy
timeoutMs {int} - the per-read idle timeout in milliseconds

Returns {Client} - a new client with the timeout set

Structs

`rest.Client`

A REST client: a base URL every path joins onto, default headers sent with every request (auth lives here), and the http.Options request policy (per-request timeout, body cap, redirect-following, retry / backoff, and TLS) applied to every call. Value-semantic; thread it per call.

Field	Type	Description
`baseUrl`	`string`	the base URL every path joins onto
`headers`	`map of string to string`	default headers sent with every request
`options`	`http.Options`	the request policy (timeout, cap, redirects, retries, tls); zero value = defaults, full TLS verification, no redirects / retries

`rest.Response`

A REST response: the status code, response headers, and the body text.

Field	Type	Description
`status`	`int`	the HTTP status code
`headers`	`map of string to string`	the response headers (lowercased keys)
`body`	`string`	the response body text

#rest API reference

#Functions

#rest.basic(user as string, pass as string)

#rest.bearer(token as string)

#rest.client(baseUrl as string)

#rest.delete(c as Client, path as string, query as map of string to string)

#rest.get(c as Client, path as string, query as map of string to string)

#rest.getJson(c as Client, path as string, query as map of string to string)

#rest.insecure(c as Client)

#rest.paginate(c as Client, path as string, query as map of string to string, maxPages as int)

#rest.paginateCursor(c as Client, path as string, query as map of string to string, cursorPointer as string, cursorParam as string, maxPages as int)

#rest.patch(c as Client, path as string, contentType as string, body as string)

#rest.patchJson(c as Client, path as string, body as json.Value)

#rest.post(c as Client, path as string, contentType as string, body as string)

#rest.postJson(c as Client, path as string, body as json.Value)

#rest.put(c as Client, path as string, contentType as string, body as string)

#rest.putJson(c as Client, path as string, body as json.Value)

#rest.withBackoff(c as Client, backoffMs as int)

#rest.withCA(c as Client, pem as bytes)

#rest.withHeader(c as Client, name as string, value as string)

#rest.withRedirects(c as Client, maxRedirects as int)

#rest.withRetries(c as Client, maxRetries as int)

#rest.withTimeout(c as Client, timeoutMs as int)

#Structs

#rest.Client

#rest.Response

`rest` API reference

Functions

`rest.basic(user as string, pass as string)`

`rest.bearer(token as string)`

`rest.client(baseUrl as string)`

`rest.delete(c as Client, path as string, query as map of string to string)`

`rest.get(c as Client, path as string, query as map of string to string)`

`rest.getJson(c as Client, path as string, query as map of string to string)`

`rest.insecure(c as Client)`

`rest.paginate(c as Client, path as string, query as map of string to string, maxPages as int)`

`rest.paginateCursor(c as Client, path as string, query as map of string to string, cursorPointer as string, cursorParam as string, maxPages as int)`

`rest.patch(c as Client, path as string, contentType as string, body as string)`

`rest.patchJson(c as Client, path as string, body as json.Value)`

`rest.post(c as Client, path as string, contentType as string, body as string)`

`rest.postJson(c as Client, path as string, body as json.Value)`

`rest.put(c as Client, path as string, contentType as string, body as string)`

`rest.putJson(c as Client, path as string, body as json.Value)`

`rest.withBackoff(c as Client, backoffMs as int)`

`rest.withCA(c as Client, pem as bytes)`

`rest.withHeader(c as Client, name as string, value as string)`

`rest.withRedirects(c as Client, maxRedirects as int)`

`rest.withRetries(c as Client, maxRetries as int)`

`rest.withTimeout(c as Client, timeoutMs as int)`

Structs

`rest.Client`

`rest.Response`