Changeset 38261 in project


Ignore:
Timestamp:
03/14/20 23:55:38 (2 weeks ago)
Author:
evhan
Message:

sourcehut: Update docs and source URL

Files:
2 edited

Legend:

Unmodified
Added
Removed
  • release/5/egg-locations

    r38236 r38261  
    282282(socket "https://raw.githubusercontent.com/ursetto/{egg-name}-egg/master/{egg-name}.release-info.5")
    283283(soil "https://www.upyum.com/cgit.cgi/soil-egg/plain/soil.release-info")
     284(sourcehut "https://git.foldling.org/chicken-{egg-name}.git/release")
    284285(sparse-vectors "http://code.call-cc.org/release-info?egg={egg-name};release={chicken-release}")
    285286(spiffy "https://code.more-magic.net/{egg-name}/plain/{egg-name}.release-info")
     
    351352(timed-resource "http://code.call-cc.org/release-info?egg={egg-name};release={chicken-release}")
    352353(tokiocabinet "https://gitlab.com/svenha/tokyocabinet-tch/-/raw/master/tokyocabinet.release-info")
    353 (topham "https://git.foldling.org/chicken-{egg-name}.git/release")
     354;; (topham "https://git.foldling.org/chicken-{egg-name}.git/release")
    354355(trace "http://code.call-cc.org/release-info?egg={egg-name};release={chicken-release}")
    355356(traversal "https://raw.github.com/abarbu/traversal/master/traversal.release-info.5")
  • wiki/eggref/5/topham

    r37618 r38261  
    11== Topham
    22
    3 A simple client library for the [[https://sr.ht/|sr.ht]] REST API.
     3This egg has been renamed to [[/eggref/5/|sourcehut]]. Please refer to that egg's page for documentation.
    44
    5 [[toc:]]
     5To update your installed library, you can simply install the new version and uninstall the old one:
    66
    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 
    21 Create a new job on [[https://builds.sr.ht/|builds.sr.ht]] and fetch
    22 information 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"
     7<enscript highlight="none">
     8chicken-install -force sourcehut
     9chicken-uninstall -force topham
    4410</enscript>
    4511
    46 Subscribe 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 
    76 There 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 
    85 The 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 
    93 If both of these are set, the parameter value is used.
    94 
    95 
    96 === Creating Requests
    97 
    98 This library follows a typical [[https://en.wikipedia.org/wiki/Create,_read,_update_and_delete|CRUD]] pattern, where you (1) create a
    99 payload representing a remote resource, then (2) send it to the server
    100 with one of the {{create}}, {{retrieve}}, {{update}} or {{delete}} procedures.
    101 
    102 Resources are represented as Scheme objects per [[https://wiki.call-cc.org/eggref/5/medea|medea]]'s default
    103 JSON-to-Scheme conversion rules. Requests and responses are represented
    104 as association lists, where the first item specifies a remote endpoint
    105 from 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 
    120 Objects of this shape are referred to as "crud" throughout this
    121 documentation.
    122 
    123 
    124 === Pagination
    125 
    126 Many API responses are subject to [[https://en.wikipedia.org/wiki/Pagination|pagination]].
    127 
    128 To 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 
    146 The {{(topham)}} library provides configuration parameters and procedures
    147 for submitting CRUD requests.
    148 
    149 <parameter>(access-token) => string</parameter>
    150 <parameter>(access-token string) => string</parameter>
    151 
    152 Sets the client's API token for authentication.
    153 
    154 The value should be a [[https://man.sr.ht/meta.sr.ht/oauth-api.md#personal-access-tokens|personal access token]], which can be
    155 created (or revoked) from your [[https://meta.sr.ht/oauth|account settings page]].
    156 
    157 This library does not support OAuth-based authentication.
    158 
    159 <parameter>(service-domain) => string</parameter>
    160 <parameter>(service-domain string) => string</parameter>
    161 
    162 Specifies the hostname of the remote service, useful for connecting to a
    163 sr.ht instance other than [[https://sr.ht/]].
    164 
    165 The 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 
    172 Submits a CRUD payload to the server.
    173 
    174 These procedures correspond to the {{POST}}, {{GET}}, {{PUT}} and {{DELETE}}
    175 request methods, respectively. The result is a Scheme representation of
    176 the response (generally a "crud object"), or {{#f}} if the requested
    177 resource was not found.
    178 
    179 If 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 
    184 Sets the starting ID for results fetched with {{retrieve}}.
    185 
    186 Refer to [[#Pagination|Pagination]] for details.
    187 
    188 
    189 ==== builds
    190 
    191 The {{(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 
    197 In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches a job by ID]].
    198 
    199 In 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 
    218 The {{(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 
    234 In the first form, [[https://man.sr.ht/lists.sr.ht/api.md#get-apisubscriptionssub-id|retrieves a subscription by ID]].
    235 
    236 In 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 
    246 This 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 
    270 In the first form, [[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelistslist-name|retrieves a subscription by ID]].
    271 
    272 In the second form, [[https://man.sr.ht/lists.sr.ht/api.md#put-apilistslist-name|updates a mailing list]].
    273 
    274 In the third form, [[https://man.sr.ht/lists.sr.ht/api.md#post-apilists|creates a mailing list]].
    275 
    276 The {{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 
    282 The {{string}} arguments should be user and list names.
    283 
    284 This endpoint is subject to [[#Pagination|pagination]].
    285 
    286 
    287 ==== meta
    288 
    289 The {{(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 
    295 In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserprofile|fetches the active user's profile]].
    296 
    297 In 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 
    303 This 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 
    309 This endpoint is subject to [[#Pagination|pagination]].
    310 
    311 <procedure>(ssh-key number) => crud</procedure>
    312 <procedure>(ssh-key #!key ssh-key) => crud</procedure>
    313 
    314 In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserssh-keysid|fetches an SSH key by ID]].
    315 
    316 In 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 
    324 This endpoint is subject to [[#Pagination|pagination]].
    325 
    326 <procedure>(pgp-key number) => crud</procedure>
    327 <procedure>(pgp-key #!key pgp-key) => crud</procedure>
    328 
    329 In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserpgp-keysid|fetches a PGP key by ID]].
    330 
    331 In 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 
    338 The {{(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 
    344 In the first form, [[https://man.sr.ht/paste.sr.ht/api.md#get-apipastessha|fetches a paste by ID]].
    345 
    346 In 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 
    360 This 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 
    372 Topham is licensed under the [[https://opensource.org/licenses/BSD-3-Clause|3-clause BSD license]].
    373 
     12Note that the accompanying command line program has also been renamed accordingly.
Note: See TracChangeset for help on using the changeset viewer.