ref: 0.1.6 topham/USAGE.md -rw-r--r-- 13.1 KiB View raw
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
# Topham

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)
* [openssl](https://wiki.call-cc.org/eggref/5/openssl)
* [optimism](https://wiki.call-cc.org/eggref/5/optimism)
* [simple-exceptions](https://wiki.call-cc.org/eggref/5/simple-exceptions)

## 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")
;     (id . 1234)
;     (status . "running")
;     (setup_log ...)
;     (tasks . #(...))
;     (runner ...))

(retrieve (manifest 1234))
; => "xyz"
```

Subscribe or unsubscribe from a mailing list:

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

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

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

[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 (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](#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 by ID][get-apijobsid].

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

`number` should be a job resource ID.

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

[get-apijobsidmanifest]: https://man.sr.ht/builds.sr.ht/api.md#get-apijobsidmanifest

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

    [procedure] (user string) => crud

[Retrieves a user][get-apiuserusername].

`string` should be a username or email address.

[get-apiuserusername]: https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusername

    [procedure] (subscriptions) => crud

[Retrieves the active user's mailing list subscriptions][get-apisubscriptions].

[get-apisubscriptions]: https://man.sr.ht/lists.sr.ht/api.md#get-apisubscriptions

    [procedure] (subscription number) => crud
    [procedure] (subscription #!key list) => crud

In the first form, [retrieves a subscription by ID][get-apisubscriptionssub-id].

In the second form, [subscribes to a mailing list][post-apisubscriptions].

`number` should be a subscription resource ID.

[get-apisubscriptionssub-id]: https://man.sr.ht/lists.sr.ht/api.md#get-apisubscriptionssub-id
[post-apisubscriptions]: https://man.sr.ht/lists.sr.ht/api.md#post-apisubscriptions

    [procedure] (emails) => crud
    [procedure] (emails string) => crud

Retrieves emails sent by the [active user][get-apiemails], or by the
[given user][get-apiuserusernameemails].

`string` should be a username or email address.

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

[get-apiemails]: https://man.sr.ht/lists.sr.ht/api.md#get-apiemails
[get-apiuserusernameemails]: https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernameemails

    [procedure] (email number) => crud

[Retrieves an email][get-apiemailsemail-id].

`number` should be an email resource ID.

[get-apiemailsemail-id]: https://man.sr.ht/lists.sr.ht/api.md#get-apiemailsemail-id

    [procedure] (thread number) => crud

[Retrieves an email thread][get-apithreademail-id].

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

[get-apithreademail-id]: https://man.sr.ht/lists.sr.ht/api.md#get-apithreademail-id

    [procedure] (mailing-lists) => crud
    [procedure] (mailing-lists string) => crud

Retrieves mailing lists belonging to the [active user][get-apilists], or
to the [given user][get-apiuserusernamelists].

`string` should be a username or email address.

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

[get-apilists]: https://man.sr.ht/lists.sr.ht/api.md#get-apilists
[get-apiuserusernamelists]: https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelists

    [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][get-apiuserusernamelistslist-name].

In the second form, [updates a mailing list][put-apilistslist-name].

In the third form, [creates a mailing list][post-apilists].

The `string` arguments should be user and list names.

[get-apiuserusernamelistslist-name]: https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelistslist-name
[put-apilistslist-name]: https://man.sr.ht/lists.sr.ht/api.md#put-apilistslist-name
[post-apilists]: https://man.sr.ht/lists.sr.ht/api.md#post-apilists

    [procedure] (posts string) => crud
    [procedure] (posts string string) => crud

Retrieves posts to a mailing list, given a [list name][get-apilistslist-namepost]
or [list owner and name][get-apiuserusernamelistslist-nameposts].

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](#Pagination).

[get-apilistslist-namepost]: https://man.sr.ht/lists.sr.ht/api.md#get-apilistslist-nameposts
[get-apiuserusernamelistslist-nameposts]: https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelistslist-nameposts

#### meta

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

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

In the first form, [fetches the active user's profile][get-apiuserprofile].

In the second form, [updates the user's profile][put-apiuserprofile].

[get-apiuserprofile]: https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserprofile
[put-apiuserprofile]: https://man.sr.ht/meta.sr.ht/user-api.md#put-apiuserprofile

    [procedure] (audit-log) => crud

[Retrieves the active user's audit log][get-apiuseraudit-log].

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

[get-apiuseraudit-log]: https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuseraudit-log

    [procedure] (ssh-keys) => crud

[Retrieves the active user's SSH keys][get-apiuserssh-keys].

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

[get-apiuserssh-keys]: https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserssh-keys

    [procedure] (ssh-key number) => crud
    [procedure] (ssh-key #!key ssh-key) => crud

In the first form, [fetches an SSH key by ID][get-apiuserssh-keysid].

In the second form, [creates a new SSH key][post-apiuserssh-keys].

`number` should be a key resource ID.

[get-apiuserssh-keysid]: https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserssh-keysid
[post-apiuserssh-keys]: https://man.sr.ht/meta.sr.ht/user-api.md#post-apiuserssh-keys

    [procedure] (pgp-keys) => crud

[Retrieves the active user's PGP keys][get-apiuserpgp-keys].

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

[get-apiuserpgp-keys]: https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserpgp-keys

    [procedure] (pgp-key number) => crud
    [procedure] (pgp-key #!key pgp-key) => crud

In the first form, [fetches a PGP key by ID][get-apiuserpgp-keysid].

In the second form, [creates a new PGP key][post-apiuserpgp-keys].

`number` should be a key resource ID.

[get-apiuserpgp-keysid]: https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserpgp-keysid
[post-apiuserpgp-keys]: https://man.sr.ht/meta.sr.ht/user-api.md#post-apiuserpgp-keys

#### 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 by ID][get-apipastessha].

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

`string` should be a paste 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

[Fetches a blob][get-apiblobssha].

`string` should be a blob SHA.

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

    [procedure] (pastes) => crud

[Retrieves a list of pastes][get-apipastes].

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

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

## Links

 * Sources: <https://git.sr.ht/~evhan/topham>
 * Issues: <https://todo.sr.ht/~evhan/topham>
 * Documentation: <https://api.call-cc.org/5/doc/topham>

## License

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

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