# Topham

## Description

A simple client library for the [sr.ht](https://sr.ht/) REST API.

## Requirements

* [http-client](https://wiki.call-cc.org/eggref/5/http-client)
* [intarweb](https://wiki.call-cc.org/eggref/5/intarweb)
* [medea](https://wiki.call-cc.org/eggref/5/medea)
* [module-declarations](https://wiki.call-cc.org/eggref/5/module-declarations)

## Quick Start

Create a new job on [builds.sr.ht](https://builds.sr.ht/) and fetch
information about it:

``` scheme
(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:

```scheme
(import (topham))

(access-token "...")
```

The second is to set the `SRHT_ACCESS_TOKEN` environment variable:

```scheme
(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:

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

[CRUD]: https://en.wikipedia.org/wiki/Create,_read,_update_and_delete
[medea]: https://wiki.call-cc.org/eggref/5/medea

### Pagination

Many API responses are subject to [pagination][pagination].

To specify a starting ID, use the `page` combinator. This sets the
`start` parameter for GET requests, per [sr.ht's API][pagination-api]:

```scheme
(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))
```

[pagination]: https://en.wikipedia.org/wiki/Pagination
[pagination-api]: https://man.sr.ht/api-conventions.md#pagination

### 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][tokens], which can be
created (or revoked) from your [account settings page][oauth].

This library does not support OAuth-based authentication.

[oauth]: https://meta.sr.ht/oauth
[tokens]: https://man.sr.ht/meta.sr.ht/oauth-api.md#personal-access-tokens

    [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) => crud

Sets the starting ID for results fetched with `retrieve`.

Refer to [Pagination](#pagination) for details.

#### builds

The `(topham builds)` library provides request builders for
[builds.sr.ht](https://man.sr.ht/builds.sr.ht/api.md).

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

In the first form, [fetches a job resource by ID][get-apijobsid].

In the second form, [creates a new job resource][post-apijobs].

[get-apijobsid]: https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid
[post-apijobs]: https://man.sr.ht/builds.sr.ht/api.md#post-apijobs

    [procedure] (manifest number) => crud

[Retrieves a job's manifest][get-apijobsidmanifest].

`number` should be a job resource ID.

    [procedure] (start number) => crud

[Starts a job][post-apijobsidstart] that was created with `execute: #f`.

`number` should be a job resource ID.

[post-apijobsidstart]: https://man.sr.ht/builds.sr.ht/api.md#post-apijobsidstart

#### lists

The `(topham lists)` library provides request builders for
[lists.sr.ht](https://man.sr.ht/lists.sr.ht/api.md).

#### meta

The `(topham meta)` library provides request builders for
[meta.sr.ht](https://man.sr.ht/meta.sr.ht/api.md).

#### paste

The `(topham paste)` library provides request builders for
[paste.sr.ht](https://man.sr.ht/paste.sr.ht/api.md).

    [procedure] (paste string) => crud
    [procedure] (paste #!key contents filename visibility) => crud

In the first form, [fetches a paste resource by ID][get-apipastessha].

In the second form, [creates a new paste resource][post-apipastes].

`string` should be a paste resource SHA.

[get-apipastessha]: https://man.sr.ht/paste.sr.ht/api.md#get-apipastessha
[post-apipastes]: https://man.sr.ht/paste.sr.ht/api.md#post-apipastes

    [procedure] (blob string) => crud

[Retrieves a blob resource][get-apiblobssha].

`string` should be a blob resource SHA.

[get-apiblobssha]: https://man.sr.ht/paste.sr.ht/api.md#get-apiblobssha

    [procedure] (pastes) => crud

[Retrieves a list of paste resources][get-apipastes].

This endpoint is subject to [pagination](#pagination).

[get-apipastes]: https://man.sr.ht/paste.sr.ht/api.md#get-apipastes

## License

Topham is licensed under the [3-clause BSD license][license].

[license]: https://opensource.org/licenses/BSD-3-Clause