Transport for the Regulations.gov API: the settings resolver (per-call
opts first, then context variables, then defaults), a typed
HttpError, JSON GETs, and query-string building that drops unset
values. Keys may contain brackets (filter[docketId], page[size])
and are encoded.
| opts key | Context variable | Default |
|---|---|---|
api-key | regulations-gov.api-key | none: calls fail without it |
base-url | regulations-gov.base-url | https://api.regulations.gov/v4 |
Per-call credentials. api-key in opts is masked in call
records and never written to context, so parallel flows and tenants
in one run don't see each other's keys. Present but blank or null, it
is an error, never a fallback to context. A per-call base-url needs
an api-key in the same opts: the context key is never sent to a
per-call URL.
Context Vars
regulations-gov.api-keyregulations-gov.base-url
Values
BASE_URL
BASE_URL: Str "https://api.regulations.gov/v4"
PACKAGE_AGENT
PACKAGE_AGENT: Str "hot-dev-regulations-gov-pkg/0.1 (+https://hot.dev)"
SOURCE
SOURCE: Str "regulations-gov"
Functions
decode-body
fn (response: ::hot::http/HttpResponse, url: Str): Any
The decoded JSON of a 2xx response, or an Err carrying HttpError when
the body is not JSON (pure). Exposed for testing.
Example
url "https://api.regulations.gov/v4/documents"
ok-page ::hot::http/HttpResponse({status: 200, headers: {}, body: "{\"data\": []}"})
::regulations-gov::api/decode-body(ok-page, url) // {data: []}
html ::hot::http/HttpResponse({status: 200, headers: {}, body: "<html></html>"})
is-err(::regulations-gov::api/decode-body(html, url)) // true
get-json
fn (url: Str, headers: Map): Any
GET a JSON resource and return the decoded body, or an Err carrying
HttpError.
Example
key ::hot::ctx/get("regulations-gov.api-key")
page ::regulations-gov::api/get-json("https://api.regulations.gov/v4/documents?page%5Bsize%5D=5", {X-Api-Key: key})
length(page.data)
get-json-or-null
fn (url: Str, headers: Map): Any
get-json, but a 404 gives null (no such record) instead of an Err.
Example
key ::hot::ctx/get("regulations-gov.api-key")
doc ::regulations-gov::api/get-json-or-null("https://api.regulations.gov/v4/documents/FAA-2018-1084-0001", {X-Api-Key: key})
is-null(doc)
given
fn (v: Any): Bool
True for a non-null value that is not a blank string.
Example
::regulations-gov::api/given("EPA") // true
::regulations-gov::api/given(" ") // false
::regulations-gov::api/given(null) // false
http-error
fn (response: ::hot::http/HttpResponse, url: Str): HttpError
Build an HttpError from a non-2xx response. Exposed for testing; every
request uses it.
Example
response ::hot::http/HttpResponse({status: 429, headers: {retry-after: "60"}, body: {error: {code: "OVER_RATE_LIMIT"}}})
e ::regulations-gov::api/http-error(response, "https://api.regulations.gov/v4/documents")
e.retry-after // 60
e.message // "regulations-gov: HTTP 429: OVER_RATE_LIMIT"
is-not-found
fn (e: Any): Bool
True when e is an HttpError with status 404.
Example
::regulations-gov::api/is-not-found({status: 404}) // true
::regulations-gov::api/is-not-found({status: 500}) // false
not-json-error
fn (response: ::hot::http/HttpResponse, url: Str): HttpError
An HttpError for a 2xx response that is not JSON, such as a
maintenance page, which would otherwise read as an empty page. Exposed
for testing.
Example
response ::hot::http/HttpResponse({status: 200, headers: {}, body: "<html></html>"})
e ::regulations-gov::api/not-json-error(response, "https://api.regulations.gov/v4/documents")
e.status // 200
e.message // "regulations-gov: expected JSON from https://api.regulations.gov/v4/documents, got something else (usually an HTML page)"
path-segment
fn (value: Any): Str
Percent-encode one path segment.
Example
::regulations-gov::api/path-segment("EPA HQ") // "EPA%20HQ"
query-string
fn (params: Map): Str
Build a ?a=1&b=2 suffix from a Map, dropping null and blank values
(pure); "" when nothing remains.
Example
::regulations-gov::api/query-string({"filter[docketId]": "FAA-2018-1084", sort: null}) // "?filter%5BdocketId%5D=FAA-2018-1084"
::regulations-gov::api/query-string({sort: ""}) // ""
request
fn (method: Str, url: Str, headers: Map): ::hot::http/HttpResponse
GET (or another method) a Regulations.gov URL with headers, returning
the HttpResponse on 2xx or an Err carrying HttpError. A
transport failure passes through as its own Err.
Example
key ::hot::ctx/get("regulations-gov.api-key")
response ::regulations-gov::api/request("GET", "https://api.regulations.gov/v4/documents", {X-Api-Key: key})
response.status
require-api-key
fn (cfg: Map): Str
The API key from resolved settings, or an Err naming where to set it.
Example
cfg ::regulations-gov::api/resolve({})
key ::regulations-gov::api/require-api-key(cfg)
resolve
fn (opts: Map): Map
Resolve settings for one call: {api-key, base-url}. Values in
opts win over context; an api-key in opts is used for that call
only and comes back unchanged. An Err when api-key is in opts but
blank or null, or when opts has base-url without api-key.
Example
cfg ::regulations-gov::api/resolve({api-key: ::hot::ctx/get("regulations-gov.api-key")})
cfg.base-url
Types
HttpError
HttpError type {
source: Str,
status: Int,
url: Str,
headers: Map,
body: Any,
retry-after: Int?,
message: Str
}
A failed Regulations.gov response. source is "regulations-gov"; url
the requested URL (the key travels in the X-Api-Key header, never
the URL); retry-after the parsed Retry-After seconds on 429s;
message a one-line summary that never includes credentials. status
is normally non-2xx, but it is 200 when the site answered with
something other than JSON (see decode-body).