~evhan/chicken-sourcehut

ref: 0.1.6 chicken-sourcehut/USAGE.md -rw-r--r-- 13.1 KiB View raw
f7a80727Evan Hanson Add static build and deploy to manifest 1 year, 22 days ago

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.

[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 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 by ID.

In the second form, creates a new job.

number should be a job resource ID.

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

[procedure] (user string) => crud

Retrieves a user.

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

Retrieves an email.

number should be an email resource ID.

[procedure] (thread number) => crud

Retrieves an email thread.

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 be a mailing list name, where the list is assumed to belong 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.

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 by ID.

In the second form, creates a new paste.

string should be a paste SHA.

[procedure] (blob string) => crud

Fetches a blob.

string should be a blob SHA.

[procedure] (pastes) => crud

Retrieves a list of pastes.

This endpoint is subject to pagination.

License

Topham is licensed under the 3-clause BSD license.