Minimal client for the Software Heritage Web API (https://archive.softwareheritage.org/api/1/).
Every function takes an optional opts map as last argument:
{:base-url "https://archive.softwareheritage.org/api/1" ; default
:token "…" ; SWH bearer token (raises rate limits)
:timeout-ms 60000 ; per request; default 60 s
:keywordize? true ; keyword keys in parsed responses
:request f} ; testing hook: replaces the HTTP call
Responses are parsed JSON. HTTP errors throw ex-info with :status and :path in their ex-data; a 429 also carries {:rate-limited true :retry-after <seconds>}.
The X-RateLimit-* headers of a response are exposed as {:rate-limit {:limit <n> :remaining <n> :reset <epoch seconds>}} in the metadata of the result when it is a map or a vector (a nil result carries none), and in the ex-data of HTTP errors. A key is absent when its header is missing or not a number.
Runs on the JVM and Babashka (babashka.http-client and cheshire are built into bb).
Minimal client for the Software Heritage Web API
(https://archive.softwareheritage.org/api/1/).
Every function takes an optional `opts` map as last argument:
{:base-url "https://archive.softwareheritage.org/api/1" ; default
:token "…" ; SWH bearer token (raises rate limits)
:timeout-ms 60000 ; per request; default 60 s
:keywordize? true ; keyword keys in parsed responses
:request f} ; testing hook: replaces the HTTP call
Responses are parsed JSON. HTTP errors throw ex-info with :status and
:path in their ex-data; a 429 also carries {:rate-limited true
:retry-after <seconds>}.
The X-RateLimit-* headers of a response are exposed as
{:rate-limit {:limit <n> :remaining <n> :reset <epoch seconds>}}
in the metadata of the result when it is a map or a vector (a nil
result carries none), and in the ex-data of HTTP errors. A key is
absent when its header is missing or not a number.
Runs on the JVM and Babashka (babashka.http-client and cheshire are
built into bb).How long a request may take, in milliseconds.
How long a request may take, in milliseconds.
(known swhids)(known swhids opts)Which of swhids (strings or SWHID maps) are present in the archive?
Returns {core-swhid-string boolean}. Batches requests by 1000; the
:rate-limit metadata is the latest one received. When a batch fails
with an HTTP error, the results of the previous batches are under
:partial in the metadata of the ex-data (not in the ex-data itself,
which gets printed with the exception); an IOException goes through
as is, without them.
Which of `swhids` (strings or SWHID maps) are present in the archive?
Returns {core-swhid-string boolean}. Batches requests by 1000; the
:rate-limit metadata is the latest one received. When a batch fails
with an HTTP error, the results of the previous batches are under
:partial in the metadata of the ex-data (not in the ex-data itself,
which gets printed with the exception); an IOException goes through
as is, without them.(latest-visit origin-url)(latest-visit origin-url
{:keys [require-snapshot?] :or {require-snapshot? true} :as opts})Latest archival visit of origin-url, nil when the origin is not in
the archive. Only visits that produced a snapshot count, unless
:require-snapshot? is false in opts. The :date of the result is the
date of the last archival.
Latest archival visit of `origin-url`, nil when the origin is not in the archive. Only visits that produced a snapshot count, unless :require-snapshot? is false in opts. The :date of the result is the date of the last archival.
(resolve-swhid swhid)(resolve-swhid swhid opts)Resolve a SWHID (string or map, qualifiers allowed) into archive metadata, including a browse URL.
Resolve a SWHID (string or map, qualifiers allowed) into archive metadata, including a browse URL.
(save-code-now! origin-url)(save-code-now! origin-url {:keys [visit-type] :or {visit-type "git"} :as opts})Ask the archive to archive origin-url now. Returns the created save
request. opts: :visit-type ("git" by default, or "hg", "svn", …).
Ask the archive to archive `origin-url` now. Returns the created save
request. opts: :visit-type ("git" by default, or "hg", "svn", …).(save-requests origin-url)(save-requests origin-url {:keys [visit-type] :or {visit-type "git"} :as opts})List the save requests already made for origin-url, most recent
first. Same :visit-type option as save-code-now!.
List the save requests already made for `origin-url`, most recent first. Same :visit-type option as save-code-now!.
(visits origin-url)(visits origin-url {:keys [per-page] :or {per-page 10} :as opts})The archival visits of origin-url, most recent first, as the archive
lists them (:date, :status, :snapshot, …); nil when the origin is not
in the archive. opts: :per-page (10 by default).
The archival visits of `origin-url`, most recent first, as the archive lists them (:date, :status, :snapshot, …); nil when the origin is not in the archive. opts: :per-page (10 by default).
(whereis swhid)(whereis swhid opts)Where the archive found the artifact swhid (string or map; its
qualifiers are dropped): a qualified SWHID string whose :origin and
:anchor qualifiers name an origin and the release or revision holding
it there; nil when the archive knows none (it answers null, or a
404). The provenance API needs an account with a special permission
(a 401 or 403 otherwise).
Where the archive found the artifact `swhid` (string or map; its qualifiers are dropped): a qualified SWHID string whose :origin and :anchor qualifiers name an origin and the release or revision holding it there; nil when the archive knows none (it answers null, or a 404). The provenance API needs an account with a special permission (a 401 or 403 otherwise).
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |