source: project/wiki/eggref/5/topham @ 37618

Last change on this file since 37618 was 37618, checked in by evhan, 6 months ago

eggref/topham: Update dependencies

File size: 11.4 KB
Line 
1== Topham
2
3A simple client library for the [[https://sr.ht/|sr.ht]] REST API.
4
5[[toc:]]
6
7
8== Requirements
9
10* [[https://wiki.call-cc.org/eggref/5/http-client|http-client]]
11* [[https://wiki.call-cc.org/eggref/5/intarweb|intarweb]]
12* [[https://wiki.call-cc.org/eggref/5/medea|medea]]
13* [[https://wiki.call-cc.org/eggref/5/module-declarations|module-declarations]]
14* [[https://wiki.call-cc.org/eggref/5/openssl|openssl]]
15* [[https://wiki.call-cc.org/eggref/5/optimism|optimism]]
16* [[https://wiki.call-cc.org/eggref/5/simple-exceptions|simple-exceptions]]
17
18
19== Quick Start
20
21Create a new job on [[https://builds.sr.ht/|builds.sr.ht]] and fetch
22information about it:
23
24<enscript highlight="scheme">
25(import (topham)
26        (topham builds))
27
28(access-token "your-access-token-goes-here")
29
30(create (job manifest: "xyz"))
31; => ((#:service "builds" #:path "/api/jobs")
32;     (id . 1234))
33
34(retrieve (job 1234))
35; => ((#:service "builds" #:path "/api/jobs/1234")
36;     (id . 1234)
37;     (status . "running")
38;     (setup_log ...)
39;     (tasks . #(...))
40;     (runner ...))
41
42(retrieve (manifest 1234))
43; => "xyz"
44</enscript>
45
46Subscribe or unsubscribe from a mailing list:
47
48<enscript highlight="scheme">
49(create (subscription list: "~sircmpwn/sr.ht-announce"))
50; => ((id . 24)
51;     (created . "2018-07-08T23:46:31+00:00")
52;     (list (name . "sr.ht-announce")
53;           (owner (canonical_name . "~sircmpwn") (name . "sircmpwn"))))
54
55(retrieve (subscriptions))
56; => ((#:service "lists" #:path "/api/subscriptions")
57;     (next . null)
58;     (results
59;       .
60;       #(((id . 24)
61;          (created . "2018-07-08T23:46:31+00:00")
62;          (list (name . "sr.ht-announce")
63;                (owner (canonical_name . "~sircmpwn") (name . "sircmpwn"))))))
64;     (total . 1)
65;     (results_per_page . 50))
66
67(delete (subscription 24))
68; => #t
69</enscript>
70
71
72== Usage
73
74=== Authentication
75
76There are two ways to authenticate API requests. The first is to set the
77{{access-token}} parameter:
78
79<enscript highlight="scheme">
80(import (topham))
81
82(access-token "...")
83</enscript>
84
85The second is to set the {{SRHT_ACCESS_TOKEN}} environment variable:
86
87<enscript highlight="scheme">
88(import (chicken process-context))
89
90(set-environment-variable! "SRHT_ACCESS_TOKEN" "...")
91</enscript>
92
93If both of these are set, the parameter value is used.
94
95
96=== Creating Requests
97
98This library follows a typical [[https://en.wikipedia.org/wiki/Create,_read,_update_and_delete|CRUD]] pattern, where you (1) create a
99payload representing a remote resource, then (2) send it to the server
100with one of the {{create}}, {{retrieve}}, {{update}} or {{delete}} procedures.
101
102Resources are represented as Scheme objects per [[https://wiki.call-cc.org/eggref/5/medea|medea]]'s default
103JSON-to-Scheme conversion rules. Requests and responses are represented
104as association lists, where the first item specifies a remote endpoint
105from which a resource should be (or has been) fetched:
106
107<enscript highlight="scheme">
108(mailing-lists)
109; => ((#:service "lists" #:path "/api/lists"))
110
111(mailing-list "foo")
112; => ((#:service "lists" #:path "/api/lists/foo"))
113
114(mailing-list name: "foo" description: "bar")
115; => ((#:service "lists" #:path "/api/lists")
116;     (name . "foo")
117;     (description . "bar"))
118</enscript>
119
120Objects of this shape are referred to as "crud" throughout this
121documentation.
122
123
124=== Pagination
125
126Many API responses are subject to [[https://en.wikipedia.org/wiki/Pagination|pagination]].
127
128To specify a starting ID, use the {{page}} combinator. This sets the
129{{start}} parameter for GET requests, per [[https://man.sr.ht/api-conventions.md#pagination|sr.ht's API]]:
130
131<enscript highlight="scheme">
132(import (only (topham) retrieve page))
133
134; retrieve the first page of results
135(retrieve (emails "~user"))
136
137; retrieve results starting from id 42
138(retrieve (page (emails "~user") 42))
139</enscript>
140
141
142=== API
143
144==== topham
145
146The {{(topham)}} library provides configuration parameters and procedures
147for submitting CRUD requests.
148
149<parameter>(access-token) => string</parameter>
150<parameter>(access-token string) => string</parameter>
151
152Sets the client's API token for authentication.
153
154The value should be a [[https://man.sr.ht/meta.sr.ht/oauth-api.md#personal-access-tokens|personal access token]], which can be
155created (or revoked) from your [[https://meta.sr.ht/oauth|account settings page]].
156
157This library does not support OAuth-based authentication.
158
159<parameter>(service-domain) => string</parameter>
160<parameter>(service-domain string) => string</parameter>
161
162Specifies the hostname of the remote service, useful for connecting to a
163sr.ht instance other than [[https://sr.ht/]].
164
165The default value is simply {{"sr.ht"}}.
166
167<procedure>(create crud) => any</procedure>
168<procedure>(retrieve crud) => any</procedure>
169<procedure>(update crud) => any</procedure>
170<procedure>(delete crud) => any</procedure>
171
172Submits a CRUD payload to the server.
173
174These procedures correspond to the {{POST}}, {{GET}}, {{PUT}} and {{DELETE}}
175request methods, respectively. The result is a Scheme representation of
176the response (generally a "crud object"), or {{#f}} if the requested
177resource was not found.
178
179If the response is an error (other than HTTP 404), a condition of type
180{{(exn http topham)}} is signaled.
181
182<procedure>(page crud) => crud</procedure>
183
184Sets the starting ID for results fetched with {{retrieve}}.
185
186Refer to [[#Pagination|Pagination]] for details.
187
188
189==== builds
190
191The {{(topham builds)}} library provides request builders for
192[[https://man.sr.ht/builds.sr.ht/api.md|builds.sr.ht]].
193
194<procedure>(job number) => crud</procedure>
195<procedure>(job #!key argument ...) => crud</procedure>
196
197In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches a job by ID]].
198
199In the second form, [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|creates a new job]].
200
201{{number}} should be a job resource ID.
202
203<procedure>(manifest number) => crud</procedure>
204
205[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsidmanifest|Retrieves a job's manifest]].
206
207{{number}} should be a job resource ID.
208
209<procedure>(start number) => crud</procedure>
210
211[[https://man.sr.ht/builds.sr.ht/api.md#post-apijobsidstart|Starts a job]] that was created with {{execute: #f}}.
212
213{{number}} should be a job resource ID.
214
215
216==== lists
217
218The {{(topham lists)}} library provides request builders for
219[[https://man.sr.ht/lists.sr.ht/api.md|lists.sr.ht]].
220
221<procedure>(user string) => crud</procedure>
222
223[[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusername|Retrieves a user]].
224
225{{string}} should be a username or email address.
226
227<procedure>(subscriptions) => crud</procedure>
228
229[[https://man.sr.ht/lists.sr.ht/api.md#get-apisubscriptions|Retrieves the active user's mailing list subscriptions]].
230
231<procedure>(subscription number) => crud</procedure>
232<procedure>(subscription #!key list) => crud</procedure>
233
234In the first form, [[https://man.sr.ht/lists.sr.ht/api.md#get-apisubscriptionssub-id|retrieves a subscription by ID]].
235
236In the second form, [[https://man.sr.ht/lists.sr.ht/api.md#post-apisubscriptions|subscribes to a mailing list]].
237
238{{number}} should be a subscription resource ID.
239
240<procedure>(emails string) => crud</procedure>
241
242[[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernameemails|Retrieves a user's emails]].
243
244{{string}} should be a username or email address.
245
246This endpoint is subject to [[#Pagination|pagination]].
247
248<procedure>(email number) => crud</procedure>
249
250[[https://man.sr.ht/lists.sr.ht/api.md#get-apiemailsemail-id|Retrieves an email]].
251
252{{number}} should be an email resource ID.
253
254<procedure>(thread number) => crud</procedure>
255
256[[https://man.sr.ht/lists.sr.ht/api.md#get-apithreademail-id|Retrieves an email thread]].
257
258{{number}} should be an email resource ID.
259
260<procedure>(mailing-lists string) => crud</procedure>
261
262[[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelists|Retrieves a user's mailing lists]].
263
264{{string}} should be a username or email address.
265
266<procedure>(mailing-list string string) => crud</procedure>
267<procedure>(mailing-list string #!key description) => crud</procedure>
268<procedure>(mailing-list #!key name description) => crud</procedure>
269
270In the first form, [[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelistslist-name|retrieves a subscription by ID]].
271
272In the second form, [[https://man.sr.ht/lists.sr.ht/api.md#put-apilistslist-name|updates a mailing list]].
273
274In the third form, [[https://man.sr.ht/lists.sr.ht/api.md#post-apilists|creates a mailing list]].
275
276The {{string}} arguments should be user and list names.
277
278<procedure>(posts string string) => crud</procedure>
279
280[[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelistslist-nameposts|Retrieves posts to a mailing list]].
281
282The {{string}} arguments should be user and list names.
283
284This endpoint is subject to [[#Pagination|pagination]].
285
286
287==== meta
288
289The {{(topham meta)}} library provides request builders for
290[[https://man.sr.ht/meta.sr.ht/api.md|meta.sr.ht]].
291
292<procedure>(profile) => crud</procedure>
293<procedure>(profile #!key argument ...) => crud</procedure>
294
295In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserprofile|fetches the active user's profile]].
296
297In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#put-apiuserprofile|updates the user's profile]].
298
299<procedure>(audit-log) => crud</procedure>
300
301[[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuseraudit-log|Retrieves the active user's audit log]].
302
303This endpoint is subject to [[#Pagination|pagination]].
304
305<procedure>(ssh-keys) => crud</procedure>
306
307[[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserssh-keys|Retrieves the active user's SSH keys]].
308
309This endpoint is subject to [[#Pagination|pagination]].
310
311<procedure>(ssh-key number) => crud</procedure>
312<procedure>(ssh-key #!key ssh-key) => crud</procedure>
313
314In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserssh-keysid|fetches an SSH key by ID]].
315
316In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#post-apiuserssh-keys|creates a new SSH key]].
317
318{{number}} should be a key resource ID.
319
320<procedure>(pgp-keys) => crud</procedure>
321
322[[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserpgp-keys|Retrieves the active user's PGP keys]].
323
324This endpoint is subject to [[#Pagination|pagination]].
325
326<procedure>(pgp-key number) => crud</procedure>
327<procedure>(pgp-key #!key pgp-key) => crud</procedure>
328
329In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserpgp-keysid|fetches a PGP key by ID]].
330
331In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#post-apiuserpgp-keys|creates a new PGP key]].
332
333{{number}} should be a key resource ID.
334
335
336==== paste
337
338The {{(topham paste)}} library provides request builders for
339[[https://man.sr.ht/paste.sr.ht/api.md|paste.sr.ht]].
340
341<procedure>(paste string) => crud</procedure>
342<procedure>(paste #!key contents filename visibility) => crud</procedure>
343
344In the first form, [[https://man.sr.ht/paste.sr.ht/api.md#get-apipastessha|fetches a paste by ID]].
345
346In the second form, [[https://man.sr.ht/paste.sr.ht/api.md#post-apipastes|creates a new paste]].
347
348{{string}} should be a paste SHA.
349
350<procedure>(blob string) => crud</procedure>
351
352[[https://man.sr.ht/paste.sr.ht/api.md#get-apiblobssha|Fetches a blob]].
353
354{{string}} should be a blob SHA.
355
356<procedure>(pastes) => crud</procedure>
357
358[[https://man.sr.ht/paste.sr.ht/api.md#get-apipastes|Retrieves a list of pastes]].
359
360This endpoint is subject to [[#Pagination|pagination]].
361
362
363== Links
364
365* Sources: [[https://git.sr.ht/~evhan/topham]]
366* Issues: [[https://todo.sr.ht/~evhan/topham]]
367* Documentation: [[https://api.call-cc.org/5/doc/topham]]
368
369
370== License
371
372Topham is licensed under the [[https://opensource.org/licenses/BSD-3-Clause|3-clause BSD license]].
373
Note: See TracBrowser for help on using the repository browser.