sourcehut

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

TOC »

Sourcehut
Requirements
Quick Start
Usage
- Authentication
- Creating Requests
- Pagination
- API
  - sourcehut
  - builds
  - git
  - lists
  - meta
  - paste
Links
License

Quick Start

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

Usage

Authentication

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))

API

sourcehut

The (sourcehut) library provides configuration parameters and procedures for submitting API 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 sourcehut) is signaled.

page crudprocedure

Sets the starting ID for results fetched with retrieve.

Refer to Pagination for details.

builds

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

git

The (sourcehut git) library provides request builders for git.sr.ht.

log stringprocedure

log string stringprocedure

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 belonging to the given user.

This endpoint is subject to pagination.

log stringprocedure

log string stringprocedure

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.

artifact string string #!key file filenameprocedure

artifact string string string #!key file filenameprocedure

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 belonging to 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.