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

Last change on this file since 37561 was 37561, checked in by evhan, 10 months ago

egg-locations: Add topham

File size: 6.5 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" #:method GET)
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 in particular are represented
79as association lists, where the first item specifies a remote endpoint:
80
81<enscript highlight="scheme"> 
82(mailing-lists)
83; => ((#:service "lists" #:path "/api/lists" #:method GET))
84
85(mailing-list name: "foo" description: "bar")
86; => ((#:service "lists" #:path "/api/lists" #:method POST)
87;     (name . "foo")
88;     (description . "bar"))
89
90(mailing-list "foo")
91; => ((#:service "lists" #:path "/api/lists/foo" #:method GET))
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://en.wikipedia.org/wiki/Pagination|sr.ht's API]]:
104
105<enscript highlight="scheme"> 
106(import (only (topham) retrieve page))
107
108; retrieve the first page of results
109(retrieve (emails "~user"))
110
111; retrieve results starting from id 42
112(retrieve (page (emails "~user") 42))
113</enscript>
114
115
116=== API
117
118==== topham
119
120The {{(topham)}} library provides configuration parameters and procedures
121for submitting CRUD requests.
122
123<parameter>(access-token) => string</parameter>
124<parameter>(access-token string) => string</parameter>
125
126Sets the client's API token for authentication.
127
128The value should be a [[https://man.sr.ht/meta.sr.ht/oauth-api.md#personal-access-tokens|personal access token]], which can be
129created (or revoked) from your [[https://meta.sr.ht/oauth|account settings page]].
130
131This library does not support OAuth-based authentication.
132
133<parameter>(service-domain) => string</parameter>
134<parameter>(service-domain string) => string</parameter>
135
136Specifies the hostname of the remote service, useful for connecting to a
137sr.ht instance other than [[https://sr.ht/]].
138
139The default value is simply {{"sr.ht"}}.
140
141<procedure>(create crud) => any</procedure>
142<procedure>(retrieve crud) => any</procedure>
143<procedure>(update crud) => any</procedure>
144<procedure>(delete crud) => any</procedure>
145
146Submits a CRUD payload to the server.
147
148These procedures correspond to the {{POST}}, {{GET}}, {{PUT}} and {{DELETE}}
149request methods, respectively. The result is a Scheme representation of
150the response, or {{#f}} if the requested resource was not found.
151
152If the response is an error (other than HTTP 404), a condition of type
153{{(exn http topham)}} is signaled.
154
155If the given payload expects to be submitted with a different method, a
156condition of type {{(exn request topham)}} is signaled.
157
158<procedure>(page crud) => crud</procedure>
159
160Sets the starting ID for results fetched with {{retrieve}}.
161
162Refer to [[#pagination|Pagination]] for details.
163
164
165==== builds
166
167The {{(topham builds)}} library provides request builders for
168[[https://man.sr.ht/builds.sr.ht/api.md|builds.sr.ht]].
169
170<procedure>(job number) => crud</procedure>
171<procedure>(job #!key argument ...) => crud</procedure>
172
173In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches a job resource by ID]].
174
175In the second form, [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|creates a new job resource]].
176
177<procedure>(manifest number) => crud</procedure>
178
179[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|Retrieves a job's manifest]].
180
181{{number}} should be a job resource ID.
182
183<procedure>(start number) => crud</procedure>
184
185[[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|Starts a job]] that was created with {{execute: #f}}.
186
187{{number}} should be a job resource ID.
188
189
190==== lists
191
192The {{(topham lists)}} library provides request builders for
193[[https://man.sr.ht/lists.sr.ht/api.md|lists.sr.ht]].
194
195
196==== meta
197
198The {{(topham meta)}} library provides request builders for
199[[https://man.sr.ht/meta.sr.ht/api.md|meta.sr.ht]].
200
201
202==== paste
203
204The {{(topham paste)}} library provides request builders for
205[[https://man.sr.ht/paste.sr.ht/api.md|paste.sr.ht]].
206
207<procedure>(paste string) => crud</procedure>
208<procedure>(paste #!key contents filename visibility) => crud</procedure>
209
210In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches a paste resource by ID]].
211
212In the second form, [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|creates a new paste resource]].
213
214{{string}} should be a paste resource SHA.
215
216<procedure>(blob string) => crud</procedure>
217
218[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|Retrieves a blob resource]].
219
220{{string}} should be a blob resource SHA.
221
222<procedure>(pastes) => crud</procedure>
223
224[[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|Retrieves a list of paste resources]].
225
226This endpoint is subject to [[#pagination|pagination]].
227
228
229== License
230
231Topham is licensed under the [[https://opensource.org/licenses/BSD-3-Clause|3-clause BSD license]].
232
Note: See TracBrowser for help on using the repository browser.