go-shiori · fmartingr · May 26, 2022 · Mar 1, 2022 · May 26, 2022 · May 26, 2022
diff --git a/README.md b/README.md
@@ -9,7 +9,6 @@
 
 Shiori is a simple bookmarks manager written in the Go language. Intended as a simple clone of [Pocket][pocket]. You can use it as a command line application or as a web application. This application is distributed as a single binary, which means it can be installed and used easily.
 
-
 ![Screenshot][screenshot]
 
 ## Features
@@ -28,13 +27,13 @@ Shiori is a simple bookmarks manager written in the Go language. Intended as a s
 
 ## Documentation
 
-All documentation is available in the [wiki][wiki]. If you think there is incomplete or incorrect information, feel free to edit it.
+All documentation is available in the [docs folder][documentation]. If you think there is incomplete or incorrect information, feel free to edit it by submitting a pull request.
 
 ## License
 
 Shiori is distributed under the terms of the [MIT license][mit], which means you can use it and modify it however you want. However, if you make an enhancement for it, if possible, please send a pull request.
 
-[wiki]: https://github.com/go-shiori/shiori/wiki
+[documentation]: https://github.com/go-shiori/shiori/blob/master/docs/index.md
 [mit]: https://choosealicense.com/licenses/mit/
 [web-extension]: https://github.com/go-shiori/shiori-web-ext
 [screenshot]: https://raw.githubusercontent.com/go-shiori/shiori/master/docs/readme/cover.png

diff --git a/docs/API.md b/docs/API.md
@@ -0,0 +1,291 @@
+This is a brief explanation of Shiori's API. For more examples you can import this [collection](https://github.com/go-shiori/shiori/blob/master/docs/postman/shiori.postman_collection.json) in Postman.
+
+<!-- TOC -->
+
+- [Auth](#auth)
+ - [Log in](#log-in)
+ - [Log out](#log-out)
+- [Bookmarks](#bookmarks)
+ - [Get bookmarks](#get-bookmarks)
+ - [Add bookmark](#add-bookmark)
+ - [Edit bookmark](#edit-bookmark)
+ - [Delete bookmark](#delete-bookmark)
+- [Tags](#tags)
+ - [Get tags](#get-tags)
+ - [Rename tag](#rename-tag)
+- [Accounts](#accounts)
+ - [List accounts](#list-accounts)
+ - [Create account](#create-account)
+ - [Edit account](#edit-account)
+ - [Delete accounts](#delete-accounts)
+
+<!-- /TOC -->
+
+# Auth
+
+## Log in
+Most actions require a session id. For that, you'll need to log in using your username and password.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/login`|
+|Method|`POST`|
+
+Body:
+```json
+{
+ "username": "shiori",
+ "password": "gopher",
+ "remember": 1,
+ "owner": true
+}
+```
+
+It will return your session ID in a JSON:
+```json
+{
+ "session": "YOUR_SESSION_ID",
+ "account": {
+ "id": 1,
+ "username": "shiori",
+ "owner": true
+ }
+}
+```
+
+## Log out
+Log out of a session ID.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/logout`|
+|Method|`POST`|
+|`X-Session-Id` Header|`sessionId`|
+
+# Bookmarks
+## Get bookmarks
+Gets the last 30 bookmarks (last page).
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/bookmarks`|
+|Method|`GET`|
+|`X-Session-Id` Header|`sessionId`|
+
+Returns:
+```json
+{
+ "bookmarks": [
+ {
+ "id": 825,
+ "url": "https://interesting_cool_article.com",
+ "title": "Cool Interesting Article",
+ "excerpt": "An interesting and cool article indeed!",
+ "author": "",
+ "public": 0,
+ "modified": "2020-12-06 00:00:00",
+ "imageURL": "",
+ "hasContent": true,
+ "hasArchive": true,
+ "tags": [
+ {
+ "id": 7,
+ "name": "TAG"
+ }
+ ],
+ "createArchive": false
+ },
+ ],
+ "maxPage": 19,
+ "page": 1
+}
+```
+
+## Add bookmark
+Add a bookmark. For some reason, Shiori ignores the provided title and excerpt, and instead fetches them automatically. Note the tag format, a regular JSON list will result in an error.
+
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/bookmarks`|
+|Method|`POST`|
+|`X-Session-Id` Header|`sessionId`|
+
+Body:
+```json
+{
+ "url": "https://interesting_cool_article.com",
+ "createArchive": true,
+ "public": 1,
+ "tags": [{"name": "Interesting"}, {"name": "Cool"}],
+ "title": "Cool Interesting Article",
+ "excerpt": "An interesting and cool article indeed!"
+}
+```
+Returns:
+```json
+{
+ "id": 827,
+ "url": "https://interesting_cool_article.com",
+ "title": "TITLE",
+ "excerpt": "EXCERPT",
+ "author": "AUTHOR",
+ "public": 1,
+ "modified": "DATE",
+ "html": "HTML",
+ "imageURL": "/bookmark/827/thumb",
+ "hasContent": false,
+ "hasArchive": true,
+ "tags": [
+ {
+ "name": "Interesting"
+ },
+ {
+ "name": "Cool"
+ }
+ ],
+ "createArchive": true
+}
+```
+
+## Edit bookmark
+Modifies a bookmark, by ID.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/bookmarks`|
+|Method|`PUT`|
+|`X-Session-Id` Header|`sessionId`|
+
+Body:
+```json
+{
+ "id": 3,
+ "url": "https://interesting_cool_article.com",
+ "title": "Cool Interesting Article",
+ "excerpt": "An interesting and cool article indeed!",
+ "author": "AUTHOR",
+ "public": 1,
+ "modified": "2019-09-22 00:00:00",
+ "imageURL": "/bookmark/3/thumb",
+ "hasContent": false,
+ "hasArchive": false,
+ "tags": [],
+ "createArchive": false
+}
+```
+After providing the ID, provide the modified fields. The syntax is the same as [adding](#Add-a-bookmark).
+
+## Delete bookmark
+Deletes a list of bookmarks, by their IDs.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/bookmarks`|
+|Method|`DEL`|
+|`X-Session-Id` Header|`sessionId`|
+
+Body:
+```json
+[1, 2, 3]
+```
+
+# Tags
+## Get tags
+Gets the list of tags, their IDs and the number of entries that have those tags.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/tags`|
+|Method|`GET`|
+|`X-Session-Id` Header|`sessionId`|
+
+Returns:
+```json
+[
+ {
+ "id": 1,
+ "name": "Cool",
+ "nBookmarks": 1
+ },
+ {
+ "id": 2,
+ "name": "Interesting",
+ "nBookmarks": 1
+ }
+```
+
+## Rename tag
+Renames a tag, provided its ID.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/tags`|
+|Method|`PUT`|
+|`X-Session-Id` Header|`sessionId`|
+
+Body:
+```json
+{
+ "id": 1,
+ "name": "TAG_NEW_NAME"
+}
+```
+
+# Accounts
+## List accounts
+Gets the list of all user accounts, their IDs, and whether or not they are owners.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/accounts`|
+|Method|`GET`|
+|`X-Session-Id` Header|`sessionId`|
+
+Returns:
+```json
+[
+ {
+ "id": 1,
+ "username": "shiori",
+ "owner": true
+ }
+]
+```
+
+## Create account
+Creates a new user.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/accounts`|
+|Method|`POST`|
+|`X-Session-Id` Header|`sessionId`|
+Body:
+```json
+{
+ "username": "shiori2",
+ "password": "gopher",
+ "owner": false
+}
+```
+
+## Edit account
+Changes an account's password or owner status.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/accounts`|
+|Method|`PUT`|
+|`X-Session-Id` Header|`sessionId`|
+Body:
+```json
+{
+ "username": "shiori",
+ "oldPassword": "gopher",
+ "newPassword": "gopher",
+ "owner": true
+}
+```
+
+## Delete accounts
+Deletes a list of users.
+|Request info|Value|
+|-|-|
+|Endpoint|`/api/accounts`|
+|Method|`DEL`|
+|`X-Session-Id` Header|`sessionId`|
+
+Body:
+```json
+["shiori", "shiori2"]
+```
diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -0,0 +1,55 @@
+Content
+---
+
+<!-- TOC -->
+
+- [Content](#content)
+- [Data Directory](#data-directory)
+- [Database](#database)
+ - [MySQL](#mysql)
+ - [PostgreSQL](#postgresql)
+
+<!-- /TOC -->
+
+Data Directory
+---
+
+Shiori is designed to work out of the box, but you can change where it stores your bookmarks if you need to.
+
+By default, Shiori saves your bookmarks in one of the following directories:
+
+| Platform | Directory |
+|----------|--------------------------------------------------------------|
+| Linux | `${XDG_DATA_HOME}/shiori` (default: `~/.local/share/shiori`) |
+| macOS | `~/Library/Application Support/shiori` |
+| Windows | `%LOCALAPPDATA%/shiori` |
+
+If you pass the flag `--portable` to Shiori, your data will be stored in the `shiori-data` subdirectory alongside the shiori executable.
+
+To specify a custom path, set the `SHIORI_DIR` environment variable.
+
+Database
+---
+
+Shiori uses an SQLite3 database stored in the above data directory by default. If you prefer, you can also use MySQL or PostgreSQL database by setting it in environment variables.
+
+### MySQL
+
+| Variable | Description |
+|------------------------|-----------------------------------------------------|
+| `SHIORI_DBMS` | Must be set to `mysql` |
+| `SHIORI_MYSQL_USER` | Name of MySQL user |
+| `SHIORI_MYSQL_PASS` | Password for the above user |
+| `SHIORI_MYSQL_NAME` | Name of database to use |
+| `SHIORI_MYSQL_ADDRESS` | Address of MySQL server, e.g. `tcp(127.0.0.1:3306)` or `unix(/tmp/mysqld.sock)` |
+
+### PostgreSQL
+
+| Variable | Description |
+|---------------------|--------------------------------------------|
+| `SHIORI_DBMS` | Must be set to `postgresql` |
+| `SHIORI_PG_USER` | Name of PostgreSQL user |
+| `SHIORI_PG_PASS` | Password for the above user |
+| `SHIORI_PG_NAME` | Name of database to use |
+| `SHIORI_PG_HOST` | Address of PostgreSQL server |
+| `SHIORI_PG_PORT` | Port number used by PostgreSQL server |