From a3ed3de9e3b38a1ff32c9e533fe6e1283d52b05a Mon Sep 17 00:00:00 2001 From: Ted Unangst Date: Sun, 10 Nov 2019 19:49:35 -0500 Subject: [PATCH] document the API, such as it is --- docs/honk.3 | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/intro.1 | 2 ++ docs/vim.3 | 4 ++- 3 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 docs/honk.3 diff --git a/docs/honk.3 b/docs/honk.3 new file mode 100644 index 0000000..22374c1 --- /dev/null +++ b/docs/honk.3 @@ -0,0 +1,87 @@ +.\" +.\" Copyright (c) 2019 Ted Unangst +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate$ +.Dt HONK 3 +.Os +.Sh NAME +.Nm honk +.Nd API access +.Sh DESCRIPTION +In addition to the standard web interface, some functionality is +available via the +.Nm +HTTP API. +.Pp +With the exception of login, all requests should contain +the following form values. +.Bl -tag -width action +.It Fa action +The desired action. +See below. +.It Fa token +An authorization token. +.El +.Ss login +Send a POST request to +.Pa /login +with the following form values. +.Bl -tag -width username +.It Fa username +User name. +.It Fa password +Pass phrase. +.It Fa gettoken +Must be +.Dq 1 . +.El +.Pp +This will return a token to be used for future requests. +The token is valid for one year. +You can stop using the API at any time, but you can never logout. +.Ss honk +The +.Fa action +value should be +.Dq honk . +The following values are recognized: +.Bl -tag -width placename +.It Fa noise +The contents of the honk in markdown format. +.It Fa donk +A file to attach. +.It Fa donkdesc +A description for the attached file. +.It Fa placename +The name of an associated location. +.It Fa placeurl +The url of an associated location. +.It Fa placelat +The latitude of an associated location. +.It Fa placelong +The longitude of an associated location. +.It Fa timestart +The start time of an event. +.It Fa rid +The ActivityPub ID that this honk is in reply to. +.El +.Pp +Upon success, the honk action will return the URL for the created honk. +.Sh EXAMPLES +Refer to the sample code in the +.Pa toys +directory. +.Sh SEE ALSO +.Xr vim 3 diff --git a/docs/intro.1 b/docs/intro.1 index ad47eef..3c38bcf 100644 --- a/docs/intro.1 +++ b/docs/intro.1 @@ -34,6 +34,8 @@ Honk composition. Honk Filtering and Censorship System. .It Xr activitypub 7 ActivityPub implementation notes. +.It Xr honk 3 +API access for robotrons. .It Xr vim 3 Modifying honk. .El diff --git a/docs/vim.3 b/docs/vim.3 index ef60cd3..587cf0f 100644 --- a/docs/vim.3 +++ b/docs/vim.3 @@ -14,7 +14,7 @@ .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate$ -.Dt VIM 1 +.Dt VIM 3 .Os .Sh NAME .Nm vim @@ -24,3 +24,5 @@ The vital improvements module, .Nm , is used to customize and extend honk in such rare cases as the existing functionality proves insufficient. +.Sh SEE ALSO +.Xr honk 3