docs: clarify wording around API split

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I864882c5a22424cd6c8c320627fe9f006a6a6964
This commit is contained in:
raf 2026-02-10 14:46:11 +03:00
commit c535650f45
Signed by: NotAShelf
GPG key ID: 29D95B64378DB4BF

View file

@ -132,19 +132,18 @@ $ cargo run -p pinakes-ui
### Extending Pinakes
[Server API documentation]: ./api.md
[Plugin API documentation]: ./plugins.md
While Pinakes _does_ aim to be as comprehensive as humanly possible, it is not
feasible to maintain all features in one gigantic repository without taking on
an immense technical debt. To avoid this kind of resource mismanagement while
still allowing for _all_ kinds of extension, Pinakes features two features at
your convenience:
- Server API Routes
- REST API Routes
- Plugin API
### API
### REST API
[REST API documentation]: ./api.md
There exists a comprehensive UI for the server component that you may query
directly from the `/api/v1` endpoint. All other endpoints are under `/api/v1`.
@ -153,71 +152,12 @@ The server API is, of course, a part of Pinakes core design but it is also how
first-party interfaces like `pinakes-ui` and `pinakes-tui` interact with the
server. You may write your own interfaces for a running Pinakes server with
minimal effort by simply sending requests to the API through your preferred
means. See [Server API documentation] on available routes and tips on how to
means. See [REST API documentation] on available routes and tips on how to
interact with the API.
#### Media
### Plugin API
| Method | Path | Description |
| -------- | -------------------- | ------------------------------------- |
| `POST` | `/media/import` | Import a file (`{"path": "..."}`) |
| `GET` | `/media` | List media (query: `offset`, `limit`) |
| `GET` | `/media/{id}` | Get media item |
| `PATCH` | `/media/{id}` | Update metadata |
| `DELETE` | `/media/{id}` | Delete media item |
| `GET` | `/media/{id}/stream` | Stream file content |
| `POST` | `/media/{id}/open` | Open with system viewer |
#### Search
| Method | Path | Description |
| ------ | --------------- | ---------------------------------------------- |
| `GET` | `/search?q=...` | Search (query: `q`, `sort`, `offset`, `limit`) |
Search syntax: `term`, `"exact phrase"`, `field:value`, `type:pdf`, `tag:music`,
`prefix*`, `fuzzy~`, `-excluded`, `a b` (AND), `a OR b`, `(grouped)`.
#### Tags
<!-- markdownlint-disable MD013-->
| Method | Path | Description |
| -------- | --------------------------- | ------------------------------------------------ |
| `POST` | `/tags` | Create tag (`{"name": "...", "parent_id": ...}`) |
| `GET` | `/tags` | List all tags |
| `GET` | `/tags/{id}` | Get tag |
| `DELETE` | `/tags/{id}` | Delete tag |
| `POST` | `/media/{id}/tags` | Tag media (`{"tag_id": "..."}`) |
| `GET` | `/media/{id}/tags` | List media's tags |
| `DELETE` | `/media/{id}/tags/{tag_id}` | Untag media |
<!-- markdownlint-enable MD013-->
#### Collections
| Method | Path | Description |
| -------- | ---------------------------------- | ----------------- |
| `POST` | `/collections` | Create collection |
| `GET` | `/collections` | List collections |
| `GET` | `/collections/{id}` | Get collection |
| `DELETE` | `/collections/{id}` | Delete collection |
| `POST` | `/collections/{id}/members` | Add member |
| `GET` | `/collections/{id}/members` | List members |
| `DELETE` | `/collections/{cid}/members/{mid}` | Remove member |
Virtual collections (kind `"virtual"`) evaluate their `filter_query` as a search
query when listing members, returning results dynamically.
#### Audit & Scanning
<!-- markdownlint-disable MD013-->
| Method | Path | Description |
| ------ | -------- | ----------------------------------------------------------------------------- |
| `GET` | `/audit` | List audit log (query: `offset`, `limit`) |
| `POST` | `/scan` | Trigger directory scan (`{"path": "/..."}` or `{"path": null}` for all roots) |
<!-- markdownlint-enable MD013-->
[Plugin API documentation]: ./plugins.md
The other method, which is by far the most powerful but also perhaps the least
polished as of writing is the **plugin system**. This is designed as a means of