You can edit this page using wiki syntax for markup.

Article contents:== Sourcehut A simple client library for the [[https://sr.ht/|sr.ht]] REST API. [[toc:]] == Requirements * [[https://wiki.call-cc.org/eggref/5/http-client|http-client]] * [[https://wiki.call-cc.org/eggref/5/intarweb|intarweb]] * [[https://wiki.call-cc.org/eggref/5/medea|medea]] * [[https://wiki.call-cc.org/eggref/5/module-declarations|module-declarations]] * [[https://wiki.call-cc.org/eggref/5/openssl|openssl]] * [[https://wiki.call-cc.org/eggref/5/optimism|optimism]] * [[https://wiki.call-cc.org/eggref/5/simple-exceptions|simple-exceptions]] * [[https://wiki.call-cc.org/eggref/5/srfi-1|srfi-1]] == Quick Start Create a new job on [[https://builds.sr.ht/|builds.sr.ht]] and fetch information about it: <enscript highlight="scheme"> (import (sourcehut) (sourcehut builds)) (access-token "your-access-token-goes-here") (create (job manifest: "xyz")) ; => ((#:service "builds" #:path "/api/jobs") ; (id . 1234)) (retrieve (job 1234)) ; => ((#:service "builds" #:path "/api/jobs/1234") ; (id . 1234) ; (status . "running") ; (setup_log ...) ; (tasks . #(...)) ; (runner ...)) (retrieve (manifest 1234)) ; => "xyz" </enscript> Subscribe or unsubscribe from a mailing list: <enscript highlight="scheme"> (create (subscription list: "~sircmpwn/sr.ht-announce")) ; => ((id . 24) ; (created . "2018-07-08T23:46:31+00:00") ; (list (name . "sr.ht-announce") ; (owner (canonical_name . "~sircmpwn") (name . "sircmpwn")))) (retrieve (subscriptions)) ; => ((#:service "lists" #:path "/api/subscriptions") ; (next . null) ; (results ; . ; #(((id . 24) ; (created . "2018-07-08T23:46:31+00:00") ; (list (name . "sr.ht-announce") ; (owner (canonical_name . "~sircmpwn") (name . "sircmpwn")))))) ; (total . 1) ; (results_per_page . 50)) (delete (subscription 24)) ; => #t </enscript> == Usage === Authentication There are two ways to authenticate API requests. The first is to set the {{access-token}} parameter: <enscript highlight="scheme"> (import (sourcehut)) (access-token "...") </enscript> The second is to set the {{SRHT_ACCESS_TOKEN}} environment variable: <enscript highlight="scheme"> (import (chicken process-context)) (set-environment-variable! "SRHT_ACCESS_TOKEN" "...") </enscript> If both of these are set, the parameter value is used. === Creating Requests This library follows a typical [[https://en.wikipedia.org/wiki/Create,_read,_update_and_delete|CRUD]] pattern, where you (1) create a payload representing a remote resource, then (2) send it to the server with one of the {{create}}, {{retrieve}}, {{update}} or {{delete}} procedures. Resources are represented as Scheme objects per [[https://wiki.call-cc.org/eggref/5/medea|medea]]'s default JSON-to-Scheme conversion rules. Requests and responses are represented as association lists, where the first item specifies a remote endpoint from which a resource should be (or has been) fetched: <enscript highlight="scheme"> (mailing-lists) ; => ((#:service "lists" #:path "/api/lists")) (mailing-list "foo") ; => ((#:service "lists" #:path "/api/lists/foo")) (mailing-list name: "foo" description: "bar") ; => ((#:service "lists" #:path "/api/lists") ; (name . "foo") ; (description . "bar")) </enscript> Objects of this shape are referred to as "crud" throughout this documentation. === Pagination Many API responses are subject to [[https://en.wikipedia.org/wiki/Pagination|pagination]]. To specify a starting ID, use the {{page}} combinator. This sets the {{start}} parameter for GET requests, per [[https://man.sr.ht/api-conventions.md#pagination|sr.ht's API]]: <enscript highlight="scheme"> (import (only (sourcehut) retrieve page)) ; retrieve the first page of results (retrieve (emails "~user")) ; retrieve results starting from id 42 (retrieve (page (emails "~user") 42)) </enscript> === API ==== sourcehut The {{(sourcehut)}} library provides configuration parameters and procedures for submitting API requests. <parameter>(access-token) => string</parameter> <parameter>(access-token string) => string</parameter> Sets the client's API token for authentication. The value should be a [[https://man.sr.ht/meta.sr.ht/oauth-api.md#personal-access-tokens|personal access token]], which can be created (or revoked) from your [[https://meta.sr.ht/oauth|account settings page]]. This library does not support OAuth-based authentication. <parameter>(service-domain) => string</parameter> <parameter>(service-domain string) => string</parameter> Specifies the hostname of the remote service, useful for connecting to a sr.ht instance other than [[https://sr.ht/]]. The default value is simply {{"sr.ht"}}. <procedure>(create crud) => any</procedure> <procedure>(retrieve crud) => any</procedure> <procedure>(update crud) => any</procedure> <procedure>(delete crud) => any</procedure> Submits a CRUD payload to the server. These procedures correspond to the {{POST}}, {{GET}}, {{PUT}} and {{DELETE}} request methods, respectively. The result is a Scheme representation of the response (generally a "crud object"), or {{#f}} if the requested resource was not found. If the response is an error (other than HTTP 404), a condition of type {{(exn http sourcehut)}} is signaled. <procedure>(page crud) => crud</procedure> Sets the starting ID for results fetched with {{retrieve}}. Refer to [[#Pagination|Pagination]] for details. ==== builds The {{(sourcehut builds)}} library provides request builders for [[https://man.sr.ht/builds.sr.ht/api.md|builds.sr.ht]]. <procedure>(job number) => crud</procedure> <procedure>(job #!key argument ...) => crud</procedure> In the first form, [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsid|fetches a job by ID]]. In the second form, [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobs|creates a new job]]. {{number}} should be a job resource ID. <procedure>(manifest number) => crud</procedure> [[https://man.sr.ht/builds.sr.ht/api.md#get-apijobsidmanifest|Retrieves a job's manifest]]. {{number}} should be a job resource ID. <procedure>(start number) => crud</procedure> [[https://man.sr.ht/builds.sr.ht/api.md#post-apijobsidstart|Starts a job]] that was created with {{execute: #f}}. {{number}} should be a job resource ID. ==== git The {{(sourcehut git)}} library provides request builders for [[https://man.sr.ht/git.sr.ht/api.md|git.sr.ht]]. <procedure>(log string) => crud</procedure> <procedure>(log string string) => crud</procedure> In the first form, [[https://man.sr.ht/git.sr.ht/api.md#get-apireposnamerefs|retrieves a list of references in the given repository belonging to the active user]]. In the second form, [[https://man.sr.ht/git.sr.ht/api.md#get-apireposnamerefs|retrieves references for a repository belonging to the given user]]. This endpoint is subject to [[#Pagination|pagination]]. <procedure>(log string) => crud</procedure> <procedure>(log string string) => crud</procedure> In the first form, [[https://man.sr.ht/git.sr.ht/api.md#get-apireposnamerefs|retrieves a list of the latest commits on the default branch of the given repository belonging to the active user]]. In the second form, [[https://man.sr.ht/git.sr.ht/api.md#get-apireposnamerefs|retrieves commits for a repository of the given user]]. This endpoint is subject to [[#Pagination|pagination]]. <procedure>(artifact string string #!key file filename) => crud</procedure> <procedure>(artifact string string string #!key file filename) => crud</procedure> In the first form, [[https://man.sr.ht/git.sr.ht/api.md#post-apireposnameartifactsref|attaches an artifact to a reference in the given repository belonging to the active user]]. In the second form, [[https://man.sr.ht/git.sr.ht/api.md#post-apireposnameartifactsref|attaches an artifact to a reference in a repository belonging to the given user]]. {{file}} should either be an input port or a string containing the file contents. A {{filename}} can also be given, to specify a name for the file. If not given, the name of the input port will be used. ==== lists The {{(sourcehut lists)}} library provides request builders for [[https://man.sr.ht/lists.sr.ht/api.md|lists.sr.ht]]. <procedure>(user string) => crud</procedure> [[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusername|Retrieves a user]]. {{string}} should be a username or email address. <procedure>(subscriptions) => crud</procedure> [[https://man.sr.ht/lists.sr.ht/api.md#get-apisubscriptions|Retrieves the active user's mailing list subscriptions]]. <procedure>(subscription number) => crud</procedure> <procedure>(subscription #!key list) => crud</procedure> In the first form, [[https://man.sr.ht/lists.sr.ht/api.md#get-apisubscriptionssub-id|retrieves a subscription by ID]]. In the second form, [[https://man.sr.ht/lists.sr.ht/api.md#post-apisubscriptions|subscribes to a mailing list]]. {{number}} should be a subscription resource ID. <procedure>(emails) => crud</procedure> <procedure>(emails string) => crud</procedure> Retrieves emails sent by the [[https://man.sr.ht/lists.sr.ht/api.md#get-apiemails|active user]], or by the [[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernameemails|given user]]. {{string}} should be a username or email address. This endpoint is subject to [[#Pagination|pagination]]. <procedure>(email number) => crud</procedure> [[https://man.sr.ht/lists.sr.ht/api.md#get-apiemailsemail-id|Retrieves an email]]. {{number}} should be an email resource ID. <procedure>(thread number) => crud</procedure> [[https://man.sr.ht/lists.sr.ht/api.md#get-apithreademail-id|Retrieves an email thread]]. {{number}} should be an email resource ID. This endpoint is ''not'' subject to pagination. Rather, the result is a vector containing all emails in the thread. <procedure>(mailing-lists) => crud</procedure> <procedure>(mailing-lists string) => crud</procedure> Retrieves mailing lists belonging to the [[https://man.sr.ht/lists.sr.ht/api.md#get-apilists|active user]], or to the [[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelists|given user]]. [[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelists|Retrieves a user's mailing lists]]. {{string}} should be a username or email address. This endpoint is subject to [[#Pagination|pagination]]. <procedure>(mailing-list string string) => crud</procedure> <procedure>(mailing-list string #!key description) => crud</procedure> <procedure>(mailing-list #!key name description) => crud</procedure> In the first form, [[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelistslist-name|retrieves a subscription by ID]]. In the second form, [[https://man.sr.ht/lists.sr.ht/api.md#put-apilistslist-name|updates a mailing list]]. In the third form, [[https://man.sr.ht/lists.sr.ht/api.md#post-apilists|creates a mailing list]]. The {{string}} arguments should be user and list names. <procedure>(posts string) => crud</procedure> <procedure>(posts string string) => crud</procedure> Retrieves posts to a mailing list, given a [[https://man.sr.ht/lists.sr.ht/api.md#get-apilistslist-namepost|list name]] or [[https://man.sr.ht/lists.sr.ht/api.md#get-apiuserusernamelistslist-nameposts|list owner and name]]. In the first form, the {{string}} argument should be a mailing list name, where the list belongs to the active user. In the second form, the arguments should be a username (the list owner) and mailing list name. This endpoint is subject to [[#Pagination|pagination]]. ==== meta The {{(sourcehut meta)}} library provides request builders for [[https://man.sr.ht/meta.sr.ht/api.md|meta.sr.ht]]. <procedure>(profile) => crud</procedure> <procedure>(profile #!key argument ...) => crud</procedure> In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserprofile|fetches the active user's profile]]. In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#put-apiuserprofile|updates the user's profile]]. <procedure>(audit-log) => crud</procedure> [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuseraudit-log|Retrieves the active user's audit log]]. This endpoint is subject to [[#Pagination|pagination]]. <procedure>(ssh-keys) => crud</procedure> [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserssh-keys|Retrieves the active user's SSH keys]]. This endpoint is subject to [[#Pagination|pagination]]. <procedure>(ssh-key number) => crud</procedure> <procedure>(ssh-key #!key ssh-key) => crud</procedure> In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserssh-keysid|fetches an SSH key by ID]]. In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#post-apiuserssh-keys|creates a new SSH key]]. {{number}} should be a key resource ID. <procedure>(pgp-keys) => crud</procedure> [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserpgp-keys|Retrieves the active user's PGP keys]]. This endpoint is subject to [[#Pagination|pagination]]. <procedure>(pgp-key number) => crud</procedure> <procedure>(pgp-key #!key pgp-key) => crud</procedure> In the first form, [[https://man.sr.ht/meta.sr.ht/user-api.md#get-apiuserpgp-keysid|fetches a PGP key by ID]]. In the second form, [[https://man.sr.ht/meta.sr.ht/user-api.md#post-apiuserpgp-keys|creates a new PGP key]]. {{number}} should be a key resource ID. ==== paste The {{(sourcehut paste)}} library provides request builders for [[https://man.sr.ht/paste.sr.ht/api.md|paste.sr.ht]]. <procedure>(paste string) => crud</procedure> <procedure>(paste #!key contents filename visibility) => crud</procedure> In the first form, [[https://man.sr.ht/paste.sr.ht/api.md#get-apipastessha|fetches a paste by ID]]. In the second form, [[https://man.sr.ht/paste.sr.ht/api.md#post-apipastes|creates a new paste]]. {{string}} should be a paste SHA. <procedure>(blob string) => crud</procedure> [[https://man.sr.ht/paste.sr.ht/api.md#get-apiblobssha|Fetches a blob]]. {{string}} should be a blob SHA. <procedure>(pastes) => crud</procedure> [[https://man.sr.ht/paste.sr.ht/api.md#get-apipastes|Retrieves a list of pastes]]. This endpoint is subject to [[#Pagination|pagination]]. == Links * Sources: [[https://git.sr.ht/~evhan/chicken-sourcehut]] * Issues: [[https://todo.sr.ht/~evhan/chicken-sourcehut]] * Documentation: [[https://api.call-cc.org/5/doc/sourcehut]] This extension was named [[https://wiki.call-cc.org/eggref/5/topham|topham]] prior to version 0.2.0. == License This extension is licensed under the [[https://opensource.org/licenses/BSD-3-Clause|3-clause BSD license]]. Description of your changes:

I would like to authenticate

Spam control

What do you get when you add 11 to 10?