From 6ab0fa8a9c00d3e9e1bff033c901e54fa123c370 Mon Sep 17 00:00:00 2001 From: Thomas Sileo Date: Mon, 22 Apr 2019 11:03:48 +0200 Subject: [PATCH] Tweak the README --- README.md | 229 ++------------------------------------------ docs/activitypub.md | 9 ++ docs/api.md | 216 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 231 insertions(+), 223 deletions(-) create mode 100644 docs/activitypub.md create mode 100644 docs/api.md diff --git a/README.md b/README.md index b36465f..852c6c4 100644 --- a/README.md +++ b/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="" docker-compose -f docker-compose-dev. $ FLASK_DEBUG=1 MICROBLOGPUB_DEBUG=1 FLASK_APP=app.py POUSSETACHES_AUTH_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 ' id=http://microblob.pub/outbox//activity -``` - -#### Response - -```json -{ - "activity": "https://microblog.pub/outbox/" -} -``` - -### 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 ' id=http://microblob.pub/outbox//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 ' id=http://microblob.pub/outbox//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 ' id=http://activity-iri.tld -``` - -#### Response - -```json -{ - "activity": "https://microblog.pub/outbox/" -} -``` - -### 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 ' id=http://activity-iri.tld -``` - -#### Response - -```json -{ - "activity": "https://microblog.pub/outbox/" -} -``` - -### 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 ' actor=http://actor-iri.tld/ -``` - -#### Response - -```json -{ - "activity": "https://microblog.pub/outbox/" -} -``` - -### 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 ' actor=http://actor-iri.tld/ -``` - -#### Response - -```json -{ - "activity": "https://microblog.pub/outbox/" -} -``` - -### 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 ' content=hello -``` - -#### Response - -```json -{ - "activity": "https://microblog.pub/outbox/" -} -``` - - -### GET /api/stream - - -#### Example - -```shell -$ http GET https://microblog.pub/api/stream Authorization:'Bearer ' -``` - -#### Response - -```json -``` - ## Contributions diff --git a/docs/activitypub.md b/docs/activitypub.md new file mode 100644 index 0000000..2ca78d9 --- /dev/null +++ b/docs/activitypub.md @@ -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 diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..90e2321 --- /dev/null +++ b/docs/api.md @@ -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 ' id=http://microblob.pub/outbox//activity +``` + +#### Response + +```json +{ + "activity": "https://microblog.pub/outbox/" +} +``` + +### 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 ' id=http://microblob.pub/outbox//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 ' id=http://microblob.pub/outbox//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 ' id=http://activity-iri.tld +``` + +#### Response + +```json +{ + "activity": "https://microblog.pub/outbox/" +} +``` + +### 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 ' id=http://activity-iri.tld +``` + +#### Response + +```json +{ + "activity": "https://microblog.pub/outbox/" +} +``` + +### 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 ' actor=http://actor-iri.tld/ +``` + +#### Response + +```json +{ + "activity": "https://microblog.pub/outbox/" +} +``` + +### 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 ' actor=http://actor-iri.tld/ +``` + +#### Response + +```json +{ + "activity": "https://microblog.pub/outbox/" +} +``` + +### 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 ' content=hello +``` + +#### Response + +```json +{ + "activity": "https://microblog.pub/outbox/" +} +``` + + +### GET /api/stream + + +#### Example + +```shell +$ http GET https://microblog.pub/api/stream Authorization:'Bearer ' +``` + +#### Response + +```json +``` + +