You are looking at historical revision 37562 of this page. It may differ significantly from its current revision.

Topham

Description

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"

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.

[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, 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.

[procedure] (page crud) => crud

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.

[procedure] (job number) => crud
[procedure] (job #!key argument ...) => crud

In the first form, fetches a job resource by ID.

In the second form, creates a new job resource.

[procedure] (manifest number) => crud

Retrieves a job's manifest.

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.

lists

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

meta

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

paste

The (topham 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 resource by ID.

In the second form, creates a new paste resource.

string should be a paste resource SHA.

[procedure] (blob string) => crud

Retrieves a blob resource.

string should be a blob resource SHA.

[procedure] (pastes) => crud

Retrieves a list of paste resources.

This endpoint is subject to pagination.

License

Topham is licensed under the 3-clause BSD license.