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

Last change on this file since 37562 was 37562, checked in by evhan, 14 months ago

eggref/topham: Update docs

File size: 7.9 KB
Line 
1== Topham
2
3[[toc:]]
4
5
6== Description
7
8A simple client library for the [[https://sr.ht/|sr.ht]] REST API.
9
10
11== Requirements
12
13* [[https://wiki.call-cc.org/eggref/5/http-client|http-client]]
14* [[https://wiki.call-cc.org/eggref/5/intarweb|intarweb]]
15* [[https://wiki.call-cc.org/eggref/5/medea|medea]]
16* [[https://wiki.call-cc.org/eggref/5/module-declarations|module-declarations]]
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
46
47== Usage
48
49=== Authentication
50
51There are two ways to authenticate API requests. The first is to set the
52{{access-token}} parameter:
53
54<enscript highlight="scheme"> 
55(import (topham))
56
57(access-token "...")
58</enscript>
59
60The second is to set the {{SRHT_ACCESS_TOKEN}} environment variable:
61
62<enscript highlight="scheme"> 
63(import (chicken process-context))
64
65(set-environment-variable! "SRHT_ACCESS_TOKEN" "...")
66</enscript>
67
68If both of these are set, the parameter value is used.
69
70
71=== Creating Requests
72
73This library follows a typical [[https://en.wikipedia.org/wiki/Create,_read,_update_and_delete|CRUD]] pattern, where you (1) create a
74payload representing a remote resource, then (2) send it to the server
75with one of the {{create}}, {{retrieve}}, {{update}} or {{delete}} procedures.
76
77Resources are represented as Scheme objects per [[https://wiki.call-cc.org/eggref/5/medea|medea]]'s default
78JSON-to-Scheme conversion rules. Requests and responses are represented
79as association lists, where the first item specifies a remote endpoint
80from which a resource should be (or has been) fetched:
81
82<enscript highlight="scheme"> 
83(mailing-lists)
84; => ((#:service "lists" #:path "/api/lists"))
85
86(mailing-list "foo")
87; => ((#:service "lists" #:path "/api/lists/foo"))
88
89(mailing-list name: "foo" description: "bar")
90; => ((#:service "lists" #:path "/api/lists")
91;     (name . "foo")
92;     (description . "bar"))
93</enscript>
94
95Objects of this shape are referred to as "crud" throughout this
96documentation.
97
98
99=== Pagination
100
101Many API responses are subject to [[https://en.wikipedia.org/wiki/Pagination|pagination]].
102
103To specify a starting ID, use the {{page}} combinator. This sets the
104{{start}} parameter for GET requests, per [[https://en.wikipedia.org/wiki/Pagination|sr.ht's API]]:
105
106<enscript highlight="scheme"> 
107(import (only (topham) retrieve page))
108
109; retrieve the first page of results
110(retrieve (emails "~user"))
111
112; retrieve results starting from id 42
113(retrieve (page (emails "~user") 42))
114</enscript>
115
116
117=== API
118
119==== topham
120
121The {{(topham)}} library provides configuration parameters and procedures
122for submitting CRUD requests.
123
124<parameter>(access-token) => string</parameter>
125<parameter>(access-token string) => string</parameter>
126
127Sets the client's API token for authentication.
128
129The value should be a [[https://man.sr.ht/meta.sr.ht/oauth-api.md#personal-access-tokens|personal access token]], which can be
130created (or revoked) from your [[https://meta.sr.ht/oauth|account settings page]].
131
132This library does not support OAuth-based authentication.
133
134<parameter>(service-domain) => string</parameter>
135<parameter>(service-domain string) => string</parameter>
136
137Specifies the hostname of the remote service, useful for connecting to a
138sr.ht instance other than [[https://sr.ht/]].
139
140The default value is simply {{"sr.ht"}}.
141
142<procedure>(create crud) => any</procedure>
143<procedure>(retrieve crud) => any</procedure>
144<procedure>(update crud) => any</procedure>
145<procedure>(delete crud) => any</procedure>
146
147Submits a CRUD payload to the server.
148
149These procedures correspond to the {{POST}}, {{GET}}, {{PUT}} and {{DELETE}}
150request methods, respectively. The result is a Scheme representation of
151the response, or {{#f}} if the requested resource was not found.
152
153If the response is an error (other than HTTP 404), a condition of type
154{{(exn http topham)}} is signaled.
155
156<procedure>(page crud) => crud</procedure>
157
158Sets the starting ID for results fetched with {{retrieve}}.
159
160Refer to [[#pagination|Pagination]] for details.
161
162
163==== builds
164
165The {{(topham builds)}} library provides request builders for
166[[https://man.sr.ht/builds.sr.ht/api.md|builds.sr.ht]].
167
168<procedure>(job number) => crud</procedure>
169<procedure>(job #!key argument ...) => crud</procedure>
170
171In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches a job resource by ID]].
172
173In the second form, [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|creates a new job resource]].
174
175<procedure>(manifest number) => crud</procedure>
176
177[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|Retrieves a job's manifest]].
178
179{{number}} should be a job resource ID.
180
181<procedure>(start number) => crud</procedure>
182
183[[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|Starts a job]] that was created with {{execute: #f}}.
184
185{{number}} should be a job resource ID.
186
187
188==== lists
189
190The {{(topham lists)}} library provides request builders for
191[[https://man.sr.ht/lists.sr.ht/api.md|lists.sr.ht]].
192
193
194==== meta
195
196The {{(topham meta)}} library provides request builders for
197[[https://man.sr.ht/meta.sr.ht/api.md|meta.sr.ht]].
198
199<procedure>(profile) => crud</procedure>
200<procedure>(profile #!key argument ...) => crud</procedure>
201
202In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches the active user's profile]].
203
204In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#put-apiuserprofile|updates the user's profile]].
205
206<procedure>(audit-log) => crud</procedure>
207
208[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|Retrieves the active user's audit log]].
209
210This endpoint is subject to [[#pagination|pagination]].
211
212<procedure>(ssh-keys) => crud</procedure>
213
214[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|Retrieves the active user's SSH keys]].
215
216This endpoint is subject to [[#pagination|pagination]].
217
218<procedure>(ssh-key number) => crud</procedure>
219<procedure>(ssh-key #!key ssh-key) => crud</procedure>
220
221In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches an SSH key by ID]].
222
223In the second form, [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|creates a new SSH key]].
224
225{{number}} should be a key resource ID.
226
227<procedure>(pgp-keys) => crud</procedure>
228
229[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|Retrieves the active user's PGP keys]].
230
231This endpoint is subject to [[#pagination|pagination]].
232
233<procedure>(pgp-key number) => crud</procedure>
234<procedure>(pgp-key #!key pgp-key) => crud</procedure>
235
236In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches a PGP key by ID]].
237
238In the second form, [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|creates a new PGP key]].
239
240{{number}} should be a key resource ID.
241
242
243==== paste
244
245The {{(topham paste)}} library provides request builders for
246[[https://man.sr.ht/paste.sr.ht/api.md|paste.sr.ht]].
247
248<procedure>(paste string) => crud</procedure>
249<procedure>(paste #!key contents filename visibility) => crud</procedure>
250
251In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches a paste resource by ID]].
252
253In the second form, [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|creates a new paste resource]].
254
255{{string}} should be a paste resource SHA.
256
257<procedure>(blob string) => crud</procedure>
258
259[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|Retrieves a blob resource]].
260
261{{string}} should be a blob resource SHA.
262
263<procedure>(pastes) => crud</procedure>
264
265[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|Retrieves a list of paste resources]].
266
267This endpoint is subject to [[#pagination|pagination]].
268
269
270== License
271
272Topham is licensed under the [[https://opensource.org/licenses/BSD-3-Clause|3-clause BSD license]].
273
Note: See TracBrowser for help on using the repository browser.