1.\"
  2.\" Copyright (c) 2019 Ted Unangst
  3.\"
  4.\" Permission to use, copy, modify, and distribute this software for any
  5.\" purpose with or without fee is hereby granted, provided that the above
  6.\" copyright notice and this permission notice appear in all copies.
  7.\"
  8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 15.\"
 16.Dd $Mdocdate$
 17.Dt HONK 3
 18.Os
 19.Sh NAME
 20.Nm honk
 21.Nd API access
 22.Sh DESCRIPTION
 23In addition to the standard web interface, some functionality is
 24available via the
 25.Nm
 26HTTP API.
 27.Pp
 28With the exception of login, all requests should contain
 29the following form values.
 30.Bl -tag -width action
 31.It Fa action
 32The desired action.
 33See below.
 34.It Fa token
 35An authorization token.
 36Alternatively, may be passed in the
 37.Dq Authorization
 38HTTP header.
 39.El
 40.Pp
 41The API URL for all actions other than login and logout is
 42.Pa /api .
 43.Ss login
 44Send a POST request to
 45.Pa /dologin
 46with the following form values.
 47.Bl -tag -width username
 48.It Fa username
 49User name.
 50.It Fa password
 51Pass phrase.
 52.It Fa gettoken
 53Must be
 54.Dq 1 .
 55.El
 56.Pp
 57This will return a token to be used for future requests.
 58The token is valid for one year.
 59.Ss logout
 60Send a request to
 61.Pa /logout
 62with the
 63.Fa token
 64to be expired.
 65.Ss honk
 66The
 67.Fa action
 68value should be
 69.Dq honk .
 70The following values are recognized:
 71.Bl -tag -width placename
 72.It Fa noise
 73The contents of the honk in markdown format.
 74.It Fa donk
 75A file to attach.
 76.It Fa donkdesc
 77A description for the attached file.
 78.It Fa placename
 79The name of an associated location.
 80.It Fa placeurl
 81The url of an associated location.
 82.It Fa placelat
 83The latitude of an associated location.
 84.It Fa placelong
 85The longitude of an associated location.
 86.It Fa timestart
 87The start time of an event.
 88.It Fa rid
 89The ActivityPub ID that this honk is in reply to.
 90.El
 91.Pp
 92Upon success, the honk action will return the URL for the created honk.
 93.Ss gethonks
 94The
 95.Dq gethonks
 96.Fa action
 97can be used to query for honks.
 98The following parameters are used.
 99.Bl -tag -width placename
100.It Fa page
101Should be one of
102.Dq home
103or
104.Dq atme .
105.It Fa after
106Only return honks after the specified ID.
107.It Fa wait
108If there are no results, wait this many seconds for something to appear.
109.El
110.Pp
111The result will be returned as json.
112.Sh EXAMPLES
113Refer to the sample code in the
114.Pa toys
115directory.
116.Sh SEE ALSO
117.Xr vim 3