mirror of
https://git.sr.ht/~tsileo/microblog.pub
synced 2024-12-21 20:54:27 +00:00
Tweak the README
This commit is contained in:
Thomas Sileo
parent
ac7a87f22a
commit
6ab0fa8a9c
3 changed files with 231 additions and 223 deletions
229
README.md
229
README.md
|
|
@ -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
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
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/).
|
||||
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
|
||||
|
|
@ -85,6 +79,10 @@ To spawn the docker-compose project (running this command will also update _micr
|
|||
$ make run
|
||||
```
|
||||
|
||||
### HTTP API
|
||||
|
||||
See [docs/api.md](docs/api.md) for the internal HTTP API documentation.
|
||||
|
||||
### 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).
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
|
|
|
|||
9
docs/activitypub.md
Normal file
9
docs/activitypub.md
Normal 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
216
docs/api.md
Normal 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
|
||||
```
|
||||
|
||||
|
||||
Loading…
Reference in a new issue