chickadee » topham

Topham

A simple client library for the sr.ht REST API.

Requirements

Quick Start

Create a new job on builds.sr.ht and fetch information about it:

(import (topham)
        (topham 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

Usage

Authentication

There are two ways to authenticate API requests. The first is to set the access-token parameter:

(import (topham))

(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.

Creating Requests

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.

Pagination

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 (topham) retrieve page))

; retrieve the first page of results
(retrieve (emails "~user"))

; retrieve results starting from id 42
(retrieve (page (emails "~user") 42))

API

topham

The (topham) library provides configuration parameters and procedures for submitting CRUD requests.

access-tokenparameter
access-token stringparameter

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.

service-domainparameter
service-domain stringparameter

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".

create crudprocedure
retrieve crudprocedure
update crudprocedure
delete crudprocedure

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 topham) is signaled.

page crudprocedure

Sets the starting ID for results fetched with retrieve.

Refer to Pagination for details.

builds

The (topham builds) library provides request builders for builds.sr.ht.

job numberprocedure
job #!key argument ...procedure

In the first form, fetches a job by ID.

In the second form, creates a new job.

number should be a job resource ID.

manifest numberprocedure

Retrieves a job's manifest.

number should be a job resource ID.

start numberprocedure

Starts a job that was created with execute: #f.

number should be a job resource ID.

lists

The (topham lists) library provides request builders for lists.sr.ht.

user stringprocedure

Retrieves a user.

string should be a username or email address.

subscriptionsprocedure

Retrieves the active user's mailing list subscriptions.

subscription numberprocedure
subscription #!key listprocedure

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.

emails stringprocedure

Retrieves a user's emails.

string should be a username or email address.

This endpoint is subject to pagination.

email numberprocedure

Retrieves an email.

number should be an email resource ID.

thread numberprocedure

Retrieves an email thread.

number should be an email resource ID.

mailing-lists stringprocedure

Retrieves a user's mailing lists.

string should be a username or email address.

mailing-list string stringprocedure
mailing-list string #!key descriptionprocedure
mailing-list #!key name descriptionprocedure

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.

posts string stringprocedure

Retrieves posts to a mailing list.

The string arguments should be user and list names.

This endpoint is subject to pagination.

meta

The (topham meta) library provides request builders for meta.sr.ht.

profileprocedure
profile #!key argument ...procedure

In the first form, fetches the active user's profile.

In the second form, updates the user's profile.

audit-logprocedure

Retrieves the active user's audit log.

This endpoint is subject to pagination.

ssh-keysprocedure

Retrieves the active user's SSH keys.

This endpoint is subject to pagination.

ssh-key numberprocedure
ssh-key #!key ssh-keyprocedure

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.

pgp-keysprocedure

Retrieves the active user's PGP keys.

This endpoint is subject to pagination.

pgp-key numberprocedure
pgp-key #!key pgp-keyprocedure

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.

paste

The (topham paste) library provides request builders for paste.sr.ht.

paste stringprocedure
paste #!key contents filename visibilityprocedure

In the first form, fetches a paste by ID.

In the second form, creates a new paste.

string should be a paste SHA.

blob stringprocedure

Fetches a blob.

string should be a blob SHA.

pastesprocedure

Retrieves a list of pastes.

This endpoint is subject to pagination.

License

Topham is licensed under the 3-clause BSD license.

Contents »