diff --git a/API.md b/API.md index bac89df..9190306 100644 --- a/API.md +++ b/API.md @@ -221,8 +221,126 @@ you've been given such a URI, the starting points for discovering objects are: - The user `Person` object, whose URI can be obtained from `/oauth/verify_credentials` as described above +# The Person Object + +```json +{ + "id": "https://fig.fr33domlover.site/people/vDxKn", + "type": "Person", + "preferredUsername": "perelev", + "summary": "Cool person who makes cool stuff", + "inbox": "https://fig.fr33domlover.site/people/vDxKn/inbox", + "outbox": "https://fig.fr33domlover.site/people/vDxKn/outbox", + "followers": "https://fig.fr33domlover.site/people/vDxKn/followers", + "following": "https://fig.fr33domlover.site/people/vDxKn/following", + "sshKey": [ + "https://fig.fr33domlover.site/people/vDxKn/ssh-keys/Pn9Yn" + ] +} +``` + +# Receiving Messages + +Requests and event notifications are received as ActivityPub `Activity` objects +in the Person's `inbox` collection. Currently push notifications aren't +implemented, so client applications need to periodically GET the collection and +detect whether new items have appeared at the top. The inbox is a (typically +paged) reverse-chronologically `OrderedCollection` of `Activity` objects, as +described in the ActivityPub specification. + +## Common properties + +These would appear in every actvity: + +- `id`: ID URI of the activity +- `type`: One of the ActivityPub or ForgeFed activity types +- `actor`: ID URI of the actor who published this activity + +These would appear in some activities: + +- `capability`: ID URI of a `Grant` activity serving as authorization +- `fulfills`: If the activity was published by an automated process rather than + human command, these are ID URI(s) of the activities, to which the automated + process was reacting + +```json +{ + "id": "https://fig.fr33domlover.site/decks/W058b/outbox/nV34D", + "type": "Accept", + "actor": "https://fig.fr33domlover.site/decks/W058b", + "fulfills": [ + "https://grape.fr33domlover.site/people/WZpnG/outbox/GQvnR" + ], + "object": "https://grape.fr33domlover.site/people/WZpnG/outbox/GQvnR" +} +``` + +## Accept + +## Add + +## Apply + +## Create + +## Follow + +## Grant + +## Invite + +## Join + +## Offer + +## Push + +## Reject + +## Remove + +## Resolve + +## Revoke + +## Undo + # Publishing and Manipulating Objects All object manipulation in Vervis is done using the ActivityPub C2S API, i.e. -by POSTing `Activity` objects to the user's `outbox`. A list of supported -activities will soon be added here and/or in the ForgeFed specification. +by POSTing `Activity` objects to the user's `outbox`. + +To determine the outbox URI, you can HTTP GET the Person object as mentioned +above, and grab the URI specified by its `outbox` field. + +## Common properties + +There are properties you'd often specify in the `Activity` object, that aren't +specific to any activity type. + +- `type`: `Activity` +- `actor`: URI of the person actor +- `capability`: URI of a `Grant` activity you've received, as authorization for + the action you're requesting +- `to`, `cc`, `bto`, `bcc`: Audience, i.e. list of URIs of actors and actor + collections + +## Accept + +## Add + +## Create + +## Follow + +## Invite + +## Join + +## Offer + +## Remove + +## Resolve + +## Undo