You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
181 lines
4.0 KiB
181 lines
4.0 KiB
.\"
|
|
.\" 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.
|
|
Alternatively, may be passed in the
|
|
.Dq Authorization
|
|
HTTP header.
|
|
.El
|
|
.Pp
|
|
The API URL for all actions other than login and logout is
|
|
.Pa /api .
|
|
.Ss login
|
|
Send a POST request to
|
|
.Pa /dologin
|
|
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.
|
|
.Ss logout
|
|
Send a request to
|
|
.Pa /logout
|
|
with the
|
|
.Fa token
|
|
to be expired.
|
|
.Ss honk
|
|
The
|
|
.Fa action
|
|
value should be
|
|
.Dq honk .
|
|
Content type should be multipart/form-data if an attachment is included.
|
|
The following values are recognized:
|
|
.Bl -tag -width placename
|
|
.It Fa noise
|
|
The contents of the honk.
|
|
.It Fa format
|
|
The format of noise.
|
|
Defaults to markdown.
|
|
May also be html.
|
|
.It Fa donk
|
|
A file to attach.
|
|
.It Fa donkdesc
|
|
A description for the attached file.
|
|
.It Fa donkxid
|
|
The XID of a previously uploaded attachment.
|
|
.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.
|
|
.Ss donk
|
|
Upload just an attachment using
|
|
.Fa donk
|
|
and
|
|
.Fa donkdesc .
|
|
Content type must be multipart/form-data.
|
|
Will return the XID.
|
|
.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.
|
|
.Ss zonkit
|
|
The
|
|
.Dq zonkit
|
|
action began life as a delete function, but has since evolved some other
|
|
powers as specified by the
|
|
.Fa wherefore
|
|
parameter.
|
|
The target of the action is specified by the
|
|
.Fa what
|
|
parameter and is generally the XID of a honk.
|
|
.Pp
|
|
Wherefore must be one of the following.
|
|
.Bl -tag -width zonvoy
|
|
.It bonk
|
|
Share honk with others.
|
|
.It unbonk
|
|
Undo share.
|
|
.It save
|
|
Mark honk as saved.
|
|
.It unsave
|
|
Unmark honk as saved.
|
|
.It react
|
|
Post an emoji reaction.
|
|
A custom reaction may be specified with
|
|
.Fa reaction .
|
|
.It ack
|
|
Mark honk as read.
|
|
.It deack
|
|
Unmark honk as read.
|
|
.It zonk
|
|
Delete this honk.
|
|
.It zonvoy
|
|
Mute this thread.
|
|
What should identify a convoy.
|
|
.El
|
|
.Ss sendactivity
|
|
Send anything.
|
|
No limits, no error checking.
|
|
.Bl -tag -width public
|
|
.It Fa rcpt
|
|
An actor to deliver the message to to.
|
|
May be specified more than once.
|
|
An inbox may be specified directly by prefixing with %.
|
|
.It Fa msg
|
|
The message.
|
|
It should be a valid json activity, but yolo.
|
|
.It Fa public
|
|
Set to 1 to use shared inboxes for delivery.
|
|
.El
|
|
.Sh EXAMPLES
|
|
Refer to the sample code in the
|
|
.Pa toys
|
|
directory.
|
|
.Sh SEE ALSO
|
|
.Xr vim 3
|