2019-11-11 01:49:35 +01:00
|
|
|
.\"
|
|
|
|
|
.\" 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.
|
2019-11-12 07:10:38 +01:00
|
|
|
Alternatively, may be passed in the
|
|
|
|
|
.Dq Authorization
|
|
|
|
|
HTTP header.
|
2019-11-11 01:49:35 +01:00
|
|
|
.El
|
2019-11-11 02:26:31 +01:00
|
|
|
.Pp
|
2019-11-11 05:51:11 +01:00
|
|
|
The API URL for all actions other than login and logout is
|
2019-11-11 02:26:31 +01:00
|
|
|
.Pa /api .
|
2019-11-11 01:49:35 +01:00
|
|
|
.Ss login
|
|
|
|
|
Send a POST request to
|
2019-11-11 05:51:11 +01:00
|
|
|
.Pa /dologin
|
2019-11-11 01:49:35 +01:00
|
|
|
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.
|
2019-11-11 05:51:11 +01:00
|
|
|
.Ss logout
|
|
|
|
|
Send a request to
|
|
|
|
|
.Pa /logout
|
|
|
|
|
with the
|
|
|
|
|
.Fa token
|
|
|
|
|
to be expired.
|
2019-11-11 01:49:35 +01:00
|
|
|
.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.
|
2019-11-12 07:09:08 +01:00
|
|
|
.Ss gethonks
|
|
|
|
|
The
|
|
|
|
|
.Dq gethonks
|
|
|
|
|
.Fa action
|
|
|
|
|
can be used to query for honks.
|
|
|
|
|
The following parameters are used.
|
|
|
|
|
.Bl -tag -width placename
|
|
|
|
|
.It Fa page
|
|
|
|
|
Should be one of
|
|
|
|
|
.Dq home
|
|
|
|
|
or
|
|
|
|
|
.Dq atme .
|
|
|
|
|
.It Fa after
|
|
|
|
|
Only return honks after the specified ID.
|
|
|
|
|
.It Fa wait
|
|
|
|
|
If there are no results, wait this many seconds for something to appear.
|
|
|
|
|
.El
|
|
|
|
|
.Pp
|
|
|
|
|
The result will be returned as json.
|
2019-11-11 01:49:35 +01:00
|
|
|
.Sh EXAMPLES
|
|
|
|
|
Refer to the sample code in the
|
|
|
|
|
.Pa toys
|
|
|
|
|
directory.
|
|
|
|
|
.Sh SEE ALSO
|
|
|
|
|
.Xr vim 3
|
