forks/microblog.pub
1
0
Fork 1
mirror of https://git.sr.ht/~tsileo/microblog.pub synced 2024-11-14 18:54:27 +00:00
Code Issues Projects Releases Packages Wiki Activity

Tweak the README

Browse source
This commit is contained in:
Thomas Sileo 2019-04-22 11:03:48 +02:00
parent ac7a87f22a
commit 6ab0fa8a9c
3 changed files with 231 additions and 223 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

229
README.md
View file

@ -53,20 +53,14 @@ Getting closer to a stable release, it should be the "last" migration.
- Manually tested against [Mastodon](https://github.com/tootsuite/mastodon) and other platforms - Manually tested against [Mastodon](https://github.com/tootsuite/mastodon) and other platforms
## ActivityPub
_microblog.pub_ implements an [ActivityPub](http://activitypub.rocks/) server, it implements both the client to server API and the federated server to server API.
Activities are verified using HTTP Signatures or by fetching the content on the remote server directly.
## User Guide ## User Guide
The easiest and recommended way to run _microblog.pub_ in production is to use the provided docker-compose config. The easiest and recommended way to run _microblog.pub_ in production is to use the provided docker-compose config.
First install [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/). First install [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/).
It's the only requirements, Python is not needed on the host system. Python is not needed on the host system.
Note that all the generated data (config included) will be stored on the host (i.e. not in Docker) in `config/` and `data/`. Note that all the generated data (config included) will be stored on the host (i.e. not only in Docker) in `config/` and `data/`.
### Installation ### Installation
@ -85,6 +79,10 @@ To spawn the docker-compose project (running this command will also update _micr
$ make run $ make run
``` ```
### HTTP API
See [docs/api.md](docs/api.md) for the internal HTTP API documentation.
### Backup ### Backup
The easiest way to backup all of your data is to backup the `microblog.pub/` directory directly (that's what I do and I have been able to restore super easily). The easiest way to backup all of your data is to backup the `microblog.pub/` directory directly (that's what I do and I have been able to restore super easily).
@ -106,221 +104,6 @@ $ env POUSSETACHES_AUTH_KEY="<secret-key>" docker-compose -f docker-compose-dev.
$ FLASK_DEBUG=1 MICROBLOGPUB_DEBUG=1 FLASK_APP=app.py POUSSETACHES_AUTH_KEY="<secret-key>" flask run -p 5005 --with-threads $ FLASK_DEBUG=1 MICROBLOGPUB_DEBUG=1 FLASK_APP=app.py POUSSETACHES_AUTH_KEY="<secret-key>" flask run -p 5005 --with-threads
``` ```
## API
Your admin API key can be found at `config/admin_api_key.key`.
## ActivityPub API
### GET /
Returns the actor profile, with links to all the "standard" collections.
### GET /tags/:tag
Special collection that reference notes with the given tag.
### GET /stream
Special collection that returns the stream/inbox as displayed in the UI.
## User API
The user API is used by the admin UI (and requires a CSRF token when used with a regular user session), but it can also be accessed with an API key.
All the examples are using [HTTPie](https://httpie.org/).
### POST /api/note/delete{?id}
Deletes the given note `id` (the note must from the instance outbox).
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/note/delete Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<delete_id>"
}
```
### POST /api/note/pin{?id}
Adds the given note `id` (the note must from the instance outbox) to the featured collection (and pins it on the homepage).
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/note/pin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
```
#### Response
```json
{
"pinned": true
}
```
### POST /api/note/unpin{?id}
Removes the given note `id` (the note must from the instance outbox) from the featured collection (and un-pins it).
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/note/unpin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
```
#### Response
```json
{
"pinned": false
}
```
### POST /api/like{?id}
Likes the given activity.
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/like Authorization:'Bearer <token>' id=http://activity-iri.tld
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<like_id>"
}
```
### POST /api/boost{?id}
Boosts/Announces the given activity.
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/boost Authorization:'Bearer <token>' id=http://activity-iri.tld
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<announce_id>"
}
```
### POST /api/block{?actor}
Blocks the given actor, all activities from this actor will be dropped after that.
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/block Authorization:'Bearer <token>' actor=http://actor-iri.tld/
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<block_id>"
}
```
### POST /api/follow{?actor}
Follows the given actor.
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/follow Authorization:'Bearer <token>' actor=http://actor-iri.tld/
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<follow_id>"
}
```
### POST /api/new_note{?content,reply}
Creates a new note. `reply` is the IRI of the "replied" note if any.
Answers a **201** (Created) status code.
You can pass the `content` and `reply` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/new_note Authorization:'Bearer <token>' content=hello
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<create_id>"
}
```
### GET /api/stream
#### Example
```shell
$ http GET https://microblog.pub/api/stream Authorization:'Bearer <token>'
```
#### Response
```json
```
## Contributions ## Contributions

9
docs/activitypub.md Normal file
View file

@ -0,0 +1,9 @@
## ActivityPub
_microblog.pub_ implements an [ActivityPub](http://activitypub.rocks/) server, it implements both the client to server API and the federated server to server API.
Activities are verified using HTTP Signatures or by fetching the content on the remote server directly.
WebFinger is also required.
TODO

216
docs/api.md Normal file
View file

@ -0,0 +1,216 @@
## API
Your admin API key can be found at `config/admin_api_key.key`.
## ActivityPub API
### GET /
Returns the actor profile, with links to all the "standard" collections.
### GET /tags/:tag
Special collection that reference notes with the given tag.
### GET /stream
Special collection that returns the stream/inbox as displayed in the UI.
## User API
The user API is used by the admin UI (and requires a CSRF token when used with a regular user session), but it can also be accessed with an API key.
All the examples are using [HTTPie](https://httpie.org/).
### POST /api/note/delete{?id}
Deletes the given note `id` (the note must from the instance outbox).
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/note/delete Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<delete_id>"
}
```
### POST /api/note/pin{?id}
Adds the given note `id` (the note must from the instance outbox) to the featured collection (and pins it on the homepage).
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/note/pin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
```
#### Response
```json
{
"pinned": true
}
```
### POST /api/note/unpin{?id}
Removes the given note `id` (the note must from the instance outbox) from the featured collection (and un-pins it).
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/note/unpin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity
```
#### Response
```json
{
"pinned": false
}
```
### POST /api/like{?id}
Likes the given activity.
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/like Authorization:'Bearer <token>' id=http://activity-iri.tld
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<like_id>"
}
```
### POST /api/boost{?id}
Boosts/Announces the given activity.
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/boost Authorization:'Bearer <token>' id=http://activity-iri.tld
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<announce_id>"
}
```
### POST /api/block{?actor}
Blocks the given actor, all activities from this actor will be dropped after that.
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/block Authorization:'Bearer <token>' actor=http://actor-iri.tld/
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<block_id>"
}
```
### POST /api/follow{?actor}
Follows the given actor.
Answers a **201** (Created) status code.
You can pass the `id` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/follow Authorization:'Bearer <token>' actor=http://actor-iri.tld/
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<follow_id>"
}
```
### POST /api/new_note{?content,reply}
Creates a new note. `reply` is the IRI of the "replied" note if any.
Answers a **201** (Created) status code.
You can pass the `content` and `reply` via JSON, form data or query argument.
#### Example
```shell
$ http POST https://microblog.pub/api/new_note Authorization:'Bearer <token>' content=hello
```
#### Response
```json
{
"activity": "https://microblog.pub/outbox/<create_id>"
}
```
### GET /api/stream
#### Example
```shell
$ http GET https://microblog.pub/api/stream Authorization:'Bearer <token>'
```
#### Response
```json
```