A simple client library for the sr.ht REST API.
Create a new job on builds.sr.ht and fetch information about it:
(import (sourcehut)
(sourcehut builds))
(access-token "your-access-token-goes-here")
(create (job manifest: "xyz"))
; => ((#:service "builds" #:path "/api/jobs")
; (id . 1234))
(retrieve (job 1234))
; => ((#:service "builds" #:path "/api/jobs/1234")
; (id . 1234)
; (status . "running")
; (setup_log ...)
; (tasks . #(...))
; (runner ...))
(retrieve (manifest 1234))
; => "xyz"
Subscribe or unsubscribe from a mailing list:
(create (subscription list: "~sircmpwn/sr.ht-announce"))
; => ((id . 24)
; (created . "2018-07-08T23:46:31+00:00")
; (list (name . "sr.ht-announce")
; (owner (canonical_name . "~sircmpwn") (name . "sircmpwn"))))
(retrieve (subscriptions))
; => ((#:service "lists" #:path "/api/subscriptions")
; (next . null)
; (results
; .
; #(((id . 24)
; (created . "2018-07-08T23:46:31+00:00")
; (list (name . "sr.ht-announce")
; (owner (canonical_name . "~sircmpwn") (name . "sircmpwn"))))))
; (total . 1)
; (results_per_page . 50))
(delete (subscription 24))
; => #t
There are two ways to authenticate API requests. The first is to set the
access-token parameter:
(import (sourcehut))
(access-token "...")
The second is to set the SRHT_ACCESS_TOKEN environment variable:
(import (chicken process-context))
(set-environment-variable! "SRHT_ACCESS_TOKEN" "...")
If both of these are set, the parameter value is used.
This library follows a typical CRUD pattern, where you (1) create a
payload representing a remote resource, then (2) send it to the server
with one of the create, retrieve, update or delete procedures.
Resources are represented as Scheme objects per medea's default JSON-to-Scheme conversion rules. Requests and responses are represented as association lists, where the first item specifies a remote endpoint from which a resource should be (or has been) fetched:
(mailing-lists)
; => ((#:service "lists" #:path "/api/lists"))
(mailing-list "foo")
; => ((#:service "lists" #:path "/api/lists/foo"))
(mailing-list name: "foo" description: "bar")
; => ((#:service "lists" #:path "/api/lists")
; (name . "foo")
; (description . "bar"))
Objects of this shape are referred to as "crud" throughout this documentation.
Many API responses are subject to pagination.
To specify a starting ID, use the page combinator. This sets the
start parameter for GET requests, per sr.ht's API:
(import (only (sourcehut) retrieve page))
; retrieve the first page of results
(retrieve (emails "~user"))
; retrieve results starting from id 42
(retrieve (page (emails "~user") 42))
The (sourcehut) library provides configuration parameters and procedures
for submitting API requests.
[parameter] (access-token) => string
[parameter] (access-token string) => string
Sets the client's API token for authentication.
The value should be a personal access token, which can be created (or revoked) from your account settings page.
This library does not support OAuth-based authentication.
[parameter] (service-domain) => string
[parameter] (service-domain string) => string
Specifies the hostname of the remote service, useful for connecting to a sr.ht instance other than https://sr.ht/.
The default value is simply "sr.ht".
[procedure] (create crud) => any
[procedure] (retrieve crud) => any
[procedure] (update crud) => any
[procedure] (delete crud) => any
Submits a CRUD payload to the server.
These procedures correspond to the POST, GET, PUT and DELETE
request methods, respectively. The result is a Scheme representation of
the response (generally a "crud object"), or #f if the requested
resource was not found.
If the response is an error (other than HTTP 404), a condition of type
(exn http sourcehut) is signaled.
[procedure] (page crud) => crud
Sets the starting ID for results fetched with retrieve.
Refer to Pagination for details.
The (sourcehut builds) library provides request builders for
builds.sr.ht.
[procedure] (jobs) => crud
This endpoint is subject to pagination.
[procedure] (job number) => crud
[procedure] (job #!key argument ...) => crud
In the first form, fetches a job by ID.
In the second form, creates a new job.
number should be a job resource ID.
[procedure] (manifest number) => crud
number should be a job resource ID.
[procedure] (start number) => crud
Starts a job that was created with execute: #f.
number should be a job resource ID.
The (sourcehut git) library provides request builders for
git.sr.ht.
[procedure] (log string) => crud
[procedure] (log string string) => crud
In the first form, retrieves a list of references in the given repository belonging to the active user.
In the second form, retrieves references for a repository of the given user.
This endpoint is subject to pagination.
[procedure] (log string) => crud
[procedure] (log string string) => crud
In the first form, retrieves a list of the latest commits on the default branch of the given repository belonging to the active user.
In the second form, retrieves commits for a repository of the given user.
This endpoint is subject to pagination.
[procedure] (artifact string string #!key file filename) => crud
[procedure] (artifact string string string #!key file filename) => crud
In the first form, attaches an artifact to a reference in the given repository belonging to the active user.
In the second form, attaches an artifact to a reference in a repository of the given user.
file should either be an input port or a string containing the file
contents. A filename can also be given, to specify a name for the
file. If not given, the name of the input port will be used.
The (sourcehut lists) library provides request builders for
lists.sr.ht.
[procedure] (user string) => crud
string should be a username or email address.
[procedure] (subscriptions) => crud
Retrieves the active user's mailing list subscriptions.
[procedure] (subscription number) => crud
[procedure] (subscription #!key list) => crud
In the first form, retrieves a subscription by ID.
In the second form, subscribes to a mailing list.
number should be a subscription resource ID.
[procedure] (emails) => crud
[procedure] (emails string) => crud
Retrieves emails sent by the active user, or by the given user.
string should be a username or email address.
This endpoint is subject to pagination.
[procedure] (email number) => crud
number should be an email resource ID.
[procedure] (thread number) => crud
number should be an email resource ID.
This endpoint is not subject to pagination. Rather, the result is a vector containing all emails in the thread.
[procedure] (mailing-lists) => crud
[procedure] (mailing-lists string) => crud
Retrieves mailing lists belonging to the active user, or to the given user.
string should be a username or email address.
This endpoint is subject to pagination.
[procedure] (mailing-list string string) => crud
[procedure] (mailing-list string #!key description) => crud
[procedure] (mailing-list #!key name description) => crud
In the first form, retrieves a subscription by ID.
In the second form, updates a mailing list.
In the third form, creates a mailing list.
The string arguments should be user and list names.
[procedure] (posts string) => crud
[procedure] (posts string string) => crud
Retrieves posts to a mailing list, given a list name or list owner and name.
In the first form, the string argument should be a mailing list name,
where the list belongs to the active user.
In the second form, the arguments should be a username (the list owner) and mailing list name.
This endpoint is subject to pagination.
The (sourcehut meta) library provides request builders for
meta.sr.ht.
[procedure] (profile) => crud
[procedure] (profile #!key argument ...) => crud
In the first form, fetches the active user's profile.
In the second form, updates the user's profile.
[procedure] (audit-log) => crud
Retrieves the active user's audit log.
This endpoint is subject to pagination.
[procedure] (ssh-keys) => crud
Retrieves the active user's SSH keys.
This endpoint is subject to pagination.
[procedure] (ssh-key number) => crud
[procedure] (ssh-key #!key ssh-key) => crud
In the first form, fetches an SSH key by ID.
In the second form, creates a new SSH key.
number should be a key resource ID.
[procedure] (pgp-keys) => crud
Retrieves the active user's PGP keys.
This endpoint is subject to pagination.
[procedure] (pgp-key number) => crud
[procedure] (pgp-key #!key pgp-key) => crud
In the first form, fetches a PGP key by ID.
In the second form, creates a new PGP key.
number should be a key resource ID.
The (sourcehut paste) library provides request builders for
paste.sr.ht.
[procedure] (paste string) => crud
[procedure] (paste #!key contents filename visibility) => crud
In the first form, fetches a paste by ID.
In the second form, creates a new paste.
string should be a paste SHA.
[procedure] (blob string) => crud
string should be a blob SHA.
[procedure] (pastes) => crud
This endpoint is subject to pagination.
This extension was named topham prior to version 0.2.0.
This extension is licensed under the 3-clause BSD license.