You are looking at historical revision 37561 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" #:method GET) ; (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 in particular are represented as association lists, where the first item specifies a remote endpoint:
(mailing-lists) ; => ((#:service "lists" #:path "/api/lists" #:method GET)) (mailing-list name: "foo" description: "bar") ; => ((#:service "lists" #:path "/api/lists" #:method POST) ; (name . "foo") ; (description . "bar")) (mailing-list "foo") ; => ((#:service "lists" #:path "/api/lists/foo" #:method GET))
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.
If the given payload expects to be submitted with a different method, a condition of type (exn request topham) is signaled.
[procedure] (page crud) => crudSets 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) => crudnumber should be a job resource ID.
[procedure] (start number) => crudStarts 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.
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) => crudstring should be a blob resource SHA.
[procedure] (pastes) => crudRetrieves a list of paste resources.
This endpoint is subject to pagination.
License
Topham is licensed under the 3-clause BSD license.