2018-05-11 00:02:18 +01:00
ActivityPub Plugin for GNU Social Doc
2018-04-29 12:36:58 +01:00
=====================================
## Contents
- [Methods ](#methods )
2018-07-06 15:30:14 +01:00
- [Followers Collection ](#followers-collection )
- [Following Collection ](#following-collection )
- [Inbox ](#inbox )
- [Inbox Create ](#inbox-create )
- [Liked Collection ](#liked-collection )
- [Profiles ](#profiles )
2018-04-29 12:36:58 +01:00
- [Entities ](#entities )
2018-07-06 15:30:14 +01:00
- [Attachment ](#attachment )
- [Error ](#error )
- [Image ](#image )
- [Notice ](#notice )
- [Profile ](#profile )
- [Tag ](#tag )
2018-04-29 12:36:58 +01:00
2018-05-11 12:32:45 +01:00
###### Retrieving objects
The HTTP GET method may be dereferenced against an object's `id` property to retrieve the activity.
The plugin supports HTTP content negotiation as defined in [RFC7231 ](https://tools.ietf.org/html/rfc7231 ) in every endpoint suffixed with .json .
The plugin always presents ActivityStreams object representation in response to every request.
The client MUST specify an `Accept` header with the `application/ld+json; profile="https://www.w3.org/ns/activitystreams"` media type in order to retrieve the activity.
2018-04-29 12:36:58 +01:00
###### Selecting ranges
For most `GET` operations that return arrays, the query parameters `max_id` and `since_id` can be used to specify the range of IDs to return.
API methods that return collections of items can return a `Link` header containing URLs for the `next` and `prev` pages.
See the [Link header RFC ](https://tools.ietf.org/html/rfc5988 ) for more information.
2018-04-29 18:25:00 +01:00
###### Pretty output
For most operations if the `pretty` parameter is set a formated output will be generated (useful for learning about the API or debuging purposes).
2018-04-29 12:36:58 +01:00
###### Errors
If the request you make doesn't go through, the plugin will usually respond with an [Error ](#error ).
___
2018-05-13 14:56:59 +01:00
> **Note:** Some attributes in the payload can have ``null`` value and are marked as _nullable_ on the tables below. Attributes that are not nullable are guaranteed to return a valid value.
2018-04-29 12:36:58 +01:00
## Methods
2018-05-10 16:47:28 +01:00
### Followers Collection
2018-07-06 15:30:14 +01:00
#### Getting an Actor's Followers Collection
2018-05-10 16:47:28 +01:00
GET :nickname/followers.json
Query parameters:
2018-05-13 14:56:59 +01:00
| Field | Description | Optional | Type |
| ----------- | ------------------------- | ---------- | ---------- |
| `page` | Page index (starts in 1) | no | int32 |
2018-05-10 16:47:28 +01:00
Return:
2018-05-13 14:56:59 +01:00
| Field | Description | Nullable | Type |
| --------------- | ---------------------------- | -------- | ----------------- |
| `id` | URL of the current endpoint | no | string |
| `type` | OrderedCollectionPage | no | string |
| `totalItems` | Total number of followers | no | int32 |
| `prev` | Previous page URL | yes | string |
| `next` | Next page URL | yes | string |
| `orderedItems` | The URL of each profile | no | Array of strings |
2018-05-10 16:47:28 +01:00
2018-05-11 00:00:09 +01:00
### Following Collection
2018-07-06 15:30:14 +01:00
#### Getting an Actor's Following Collection
2018-05-11 00:00:09 +01:00
GET :nickname/following.json
Query parameters:
2018-05-13 14:56:59 +01:00
| Field | Description | Optional | Type |
| ----------- | ------------------------- | ---------- | ---------- |
| `page` | Page index (starts in 1) | no | int32 |
2018-05-11 00:00:09 +01:00
Return:
2018-05-13 14:56:59 +01:00
| Field | Description | Nullable | Type |
| --------------- | ------------------------------------ | -------- | ----------------- |
| `id` | URL for current endpoint | no | string |
| `type` | OrderedCollectionPage | no | string |
| `totalItems` | Number of persons the actor follows | no | int32 |
| `prev` | Previous page URL | yes | string |
| `next` | Next page URL | yes | string |
| `orderedItems` | The URL of each profile | no | Array of strings |
2018-05-11 00:00:09 +01:00
2018-07-06 15:30:14 +01:00
### Inbox
#### Inbox Create
POST :nickname/inbox.json
Query parameters:
| Field | Description | Optional | Type |
| --------------- | ---------------------------------------------------- | ---------- | ---------- |
| `@context` | Standard compliance | no | string |
| `id` | URL of Actor's object | no | string |
| `type` | https://www.w3.org/ns/activitystreams | no | string |
| `actor` | Actor's URL | no | string |
| `object` | Entity | no | int32 |
##### Example
###### Request:
POST https://actor_instance.localhost/nickname/inbox.json
{
"@context": "https://www.w3.org/ns/activitystreams",
"id": "https://actor_instance.com/create-hello-world",
"type": "Create",
"actor": "https://actor_instance.localhost/nickname",
"object": {
"type": "Note",
"reply_to": "http://remote_instance/notice/1337",
"content": "hello, world.",
"to": "https://www.w3.org/ns/activitystreams#Public"
}
}
###### Return:
{
"@context": "https://www.w3.org/ns/activitystreams",
"id": "https://actor_instance.com/create-hello-world",
"type": "Create",
"actor": "https://actor_instance.localhost/nickname",
"object": {
"type": "Note",
"reply_to": "http://remote_instance/notice/1337",
"content": "hello, world.",
"to": "https://www.w3.org/ns/activitystreams#Public"
}
}
2018-04-29 13:20:14 +01:00
### Liked Collection
2018-04-29 12:36:58 +01:00
2018-07-06 15:30:14 +01:00
#### Getting an Actor's Liked Collection
2018-04-29 12:36:58 +01:00
2018-04-29 18:59:13 +01:00
GET :nickname/liked.json
2018-04-29 12:36:58 +01:00
Query parameters:
2018-05-05 15:37:14 +01:00
| Field | Description | Optional | Type |
| ----------- | ---------------------------------------------------- | ---------- | ---------- |
| `max_id` | Get a list of likes with ID less than this value | yes | int32 |
| `since_id` | Get a list of likes with ID greater than this value | yes | int32 |
| `limit` | Maximum number of likes to get (Default 40, Max 80) | yes | int32 |
2018-04-29 12:36:58 +01:00
2018-04-29 13:20:14 +01:00
Return:
2018-05-13 14:56:59 +01:00
| Field | Description | Nullable | Type |
| --------------- | ---------------------------- | -------- | ---------------------------- |
| `id` | URL for current endpoint | no | string |
| `type` | OrderedCollection | no | string |
| `totalItems` | Total number of favorites | no | int32 |
| `orderedItems` | Array of [Notices ](#notice ) | no | Array of [Notices ](#notice ) |
2018-04-29 12:36:58 +01:00
2018-04-29 18:25:00 +01:00
### Profiles
2018-07-06 15:30:14 +01:00
#### Fetching an Actor's profile
2018-04-29 18:25:00 +01:00
2018-05-11 12:32:45 +01:00
GET :nickname
2018-04-29 18:25:00 +01:00
Returns a [Profile ](#profile ).
___
2018-04-29 12:36:58 +01:00
## Entities
2018-04-29 18:25:00 +01:00
### Attachment
2018-05-05 15:37:14 +01:00
| Attribute | Description | Nullable | Type |
| ------------------------ | ----------------------------------------------- | -------- | ------- |
| `id` | ID of the attachment | no | int32 |
| `mimetype` | Mimetype | no | string |
| `url` | URL of the locally hosted version of the image | no | string |
| `meta` | See **attachment metadata** below | yes | Array |
| `title` | Attachment title | no | string |
2018-04-29 18:25:00 +01:00
**Attachment metadata:**
2018-05-05 01:11:11 +01:00
Images may contain `width` , `height` , `size` .
2018-04-29 18:25:00 +01:00
### Error
The most important part of an error response is the HTTP status code. Standard semantics are followed. The body of an error is a JSON object with this structure:
2018-05-13 14:56:59 +01:00
| Attribute | Description | Nullable | Type |
| ------------------------ | ----------------------------------- | -------- | ------- |
| `error` | A textual description of the error | no | string |
2018-04-29 18:25:00 +01:00
### Image
2018-05-05 15:37:14 +01:00
| Attribute | Description | Nullable | Type |
| ------------------------ | --------------- | -------- | ------- |
| `type` | "Image" | no | string |
| `width` | Image's width | no | int32 |
| `height` | Image's height | no | int32 |
| `url` | Image URL | no | string |
2018-04-29 18:25:00 +01:00
### Notice
2018-05-05 15:37:14 +01:00
| Attribute | Description | Nullable | Type |
| ------------------------ | ------------------------------------------------- | -------- | ------------------------------------ |
| `id` | Notice's URL | no | string |
| `type` | Notice's Type | no | string |
| `actor` | URL of Notice owner profile page (can be remote) | no | string |
| `published` | DateTime of notice creation | no | datetime |
2018-07-06 15:30:14 +01:00
| `to` | To | no | string |
| `cc` | CC | no | string |
2018-05-05 15:37:14 +01:00
| `content` | Notice's Content in plain text | no | string |
| `url` | Notice's URL | no | string |
| `reply_to` | ID of the notice this replies | yes | int32 |
| `is_local` | Boolean, true if local, false otherwise | no | bool |
| `conversation` | Notice conversation id | no | int32 |
| `attachment` | Array of [Attachments ](#attachment ) | no | Array of [Attachments ](#attachment ) |
| `tag` | Array of [Tags ](#tag ) | no | Array of [Tags ](#tag ) |
2018-04-29 12:36:58 +01:00
### Profile
2018-05-05 15:37:14 +01:00
| Attribute | Description | Nullable | Type |
| ------------------------ | ------------------------------------------------ | -------- | ---------------- |
2018-07-06 15:30:14 +01:00
| `@context` | Standard compliance | no | string |
2018-05-05 15:37:14 +01:00
| `id` | Actor's id | no | int32 |
| `type` | "Person" | no | string |
| `nickname` | Actor's nickname | no | string |
| `is_local` | True if local, false otherwise | no | bool |
| `inbox` | URL to Actor's inbox endpoint | no | string |
| `outbox` | URL to Actor's outbox endpoint | no | string |
| `display_name` | The Actor's display name | no | string |
| `followers` | URL to Actor's followers endpoint | no | string |
2018-05-10 16:47:28 +01:00
| `followers_count` | Total number of followers | no | int32 |
2018-05-05 15:37:14 +01:00
| `following` | URL to Actor's following endpoint | no | string |
2018-05-10 16:47:28 +01:00
| `following_count` | Total number of following | no | int32 |
2018-05-05 15:37:14 +01:00
| `liked` | URL to Actor's Liked collection endpoint | no | string |
| `liked_count` | Total number of favorites | no | int32 |
| `summary` | Actor's biography | no | string |
| `url` | URL of the Actor's profile page (can be remote) | no | string |
| `avatar` | Actor's avatar | no | [Image ](#image ) |
2018-04-29 12:36:58 +01:00
2018-04-29 18:25:00 +01:00
### Tag
2018-04-29 12:36:58 +01:00
2018-05-05 15:37:14 +01:00
| Attribute | Description | Nullable | Type |
| ------------------------ | -------------------------------------------- | -------- | ---------- |
| `name` | The hashtag, not including the preceding `#` | no | string |
| `url` | The URL of the hashtag | no | string |