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

Last change on this file since 37563 was 37563, checked in by evhan, 13 months ago

eggref/topham: Fix broken links

File size: 8.0 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
45
46== Usage
47
48=== Authentication
49
50There are two ways to authenticate API requests. The first is to set the
51{{access-token}} parameter:
52
53<enscript highlight="scheme">
54(import (topham))
55
56(access-token "...")
57</enscript>
58
59The second is to set the {{SRHT_ACCESS_TOKEN}} environment variable:
60
61<enscript highlight="scheme">
62(import (chicken process-context))
63
64(set-environment-variable! "SRHT_ACCESS_TOKEN" "...")
65</enscript>
66
67If both of these are set, the parameter value is used.
68
69
70=== Creating Requests
71
72This library follows a typical [[https://en.wikipedia.org/wiki/Create,_read,_update_and_delete|CRUD]] pattern, where you (1) create a
73payload representing a remote resource, then (2) send it to the server
74with one of the {{create}}, {{retrieve}}, {{update}} or {{delete}} procedures.
75
76Resources are represented as Scheme objects per [[https://wiki.call-cc.org/eggref/5/medea|medea]]'s default
77JSON-to-Scheme conversion rules. Requests and responses are represented
78as association lists, where the first item specifies a remote endpoint
79from which a resource should be (or has been) fetched:
80
81<enscript highlight="scheme">
82(mailing-lists)
83; => ((#:service "lists" #:path "/api/lists"))
84
85(mailing-list "foo")
86; => ((#:service "lists" #:path "/api/lists/foo"))
87
88(mailing-list name: "foo" description: "bar")
89; => ((#:service "lists" #:path "/api/lists")
90;     (name . "foo")
91;     (description . "bar"))
92</enscript>
93
94Objects of this shape are referred to as "crud" throughout this
95documentation.
96
97
98=== Pagination
99
100Many API responses are subject to [[https://en.wikipedia.org/wiki/Pagination|pagination]].
101
102To specify a starting ID, use the {{page}} combinator. This sets the
103{{start}} parameter for GET requests, per [[https://man.sr.ht/api-conventions.md#pagination|sr.ht's API]]:
104
105<enscript highlight="scheme">
106(import (only (topham) retrieve page)
107        (only (topham paste) pastes))
108
109; retrieve the first page of results
110(retrieve (pastes))
111
112; retrieve results starting from id 42
113(retrieve (page (pastes) 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 (generally a "crud object"), or {{#f}} if the requested
152resource was not found.
153
154If the response is an error (other than HTTP 404), a condition of type
155{{(exn http topham)}} is signaled.
156
157<procedure>(page crud) => crud</procedure>
158
159Sets the starting ID for results fetched with {{retrieve}}.
160
161Refer to [[#pagination|Pagination]] for details.
162
163
164==== builds
165
166The {{(topham builds)}} library provides request builders for
167[[https://man.sr.ht/builds.sr.ht/api.md|builds.sr.ht]].
168
169<procedure>(job number) => crud</procedure>
170<procedure>(job #!key argument ...) => crud</procedure>
171
172In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches a job by ID]].
173
174In the second form, [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|creates a new job]].
175
176{{number}} should be a job resource ID.
177
178<procedure>(manifest number) => crud</procedure>
179
180[Retrieves a job's manifest][get-apijobsidmanifest].
181
182{{number}} should be a job resource ID.
183
184<procedure>(start number) => crud</procedure>
185
186[[https://man.sr.ht/builds.sr.ht/api.md#post-apijobsidstart|Starts a job]] that was created with {{execute: #f}}.
187
188{{number}} should be a job resource ID.
189
190
191==== lists
192
193The {{(topham lists)}} library provides request builders for
194[[https://man.sr.ht/lists.sr.ht/api.md|lists.sr.ht]].
195
196
197==== meta
198
199The {{(topham meta)}} library provides request builders for
200[[https://man.sr.ht/meta.sr.ht/api.md|meta.sr.ht]].
201
202<procedure>(profile) => crud</procedure>
203<procedure>(profile #!key argument ...) => crud</procedure>
204
205In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserprofile|fetches the active user's profile]].
206
207In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#put-apiuserprofile|updates the user's profile]].
208
209<procedure>(audit-log) => crud</procedure>
210
211[[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuseraudit-log|Retrieves the active user's audit log]].
212
213This endpoint is subject to [[#pagination|pagination]].
214
215<procedure>(ssh-keys) => crud</procedure>
216
217[[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserssh-keys|Retrieves the active user's SSH keys]].
218
219This endpoint is subject to [[#pagination|pagination]].
220
221<procedure>(ssh-key number) => crud</procedure>
222<procedure>(ssh-key #!key ssh-key) => crud</procedure>
223
224In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserssh-keysid|fetches an SSH key by ID]].
225
226In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#post-apiuserssh-keys|creates a new SSH key]].
227
228{{number}} should be a key resource ID.
229
230<procedure>(pgp-keys) => crud</procedure>
231
232[[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserpgp-keys|Retrieves the active user's PGP keys]].
233
234This endpoint is subject to [[#pagination|pagination]].
235
236<procedure>(pgp-key number) => crud</procedure>
237<procedure>(pgp-key #!key pgp-key) => crud</procedure>
238
239In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserpgp-keysid|fetches a PGP key by ID]].
240
241In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#post-apiuserpgp-keys|creates a new PGP key]].
242
243{{number}} should be a key resource ID.
244
245
246==== paste
247
248The {{(topham paste)}} library provides request builders for
249[[https://man.sr.ht/paste.sr.ht/api.md|paste.sr.ht]].
250
251<procedure>(paste string) => crud</procedure>
252<procedure>(paste #!key contents filename visibility) => crud</procedure>
253
254In the first form, [[https://man.sr.ht/paste.sr.ht/api.md#get-apipastessha|fetches a paste by ID]].
255
256In the second form, [[https://man.sr.ht/paste.sr.ht/api.md#post-apipastes|creates a new paste]].
257
258{{string}} should be a paste SHA.
259
260<procedure>(blob string) => crud</procedure>
261
262[[https://man.sr.ht/paste.sr.ht/api.md#get-apiblobssha|Fetches a blob]].
263
264{{string}} should be a blob SHA.
265
266<procedure>(pastes) => crud</procedure>
267
268[[https://man.sr.ht/paste.sr.ht/api.md#get-apipastes|Retrieves a list of pastes]].
269
270This endpoint is subject to [[#pagination|pagination]].
271
272
273== License
274
275Topham is licensed under the [[https://opensource.org/licenses/BSD-3-Clause|3-clause BSD license]].
276
Note: See TracBrowser for help on using the repository browser.