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

Last change on this file since 37564 was 37564, checked in by evhan, 16 months ago

eggref/topham: Add lists docs

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