From c535650f45390bc6b9c6bfb54641ca8c64f69c97 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Tue, 10 Feb 2026 14:46:11 +0300 Subject: [PATCH] docs: clarify wording around API split Signed-off-by: NotAShelf Change-Id: I864882c5a22424cd6c8c320627fe9f006a6a6964 --- docs/README.md | 74 +++++--------------------------------------------- 1 file changed, 7 insertions(+), 67 deletions(-) diff --git a/docs/README.md b/docs/README.md index 595e2af..69145fe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 - - - -| 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 | - - - -#### 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 - - - -| Method | Path | Description | -| ------ | -------- | ----------------------------------------------------------------------------- | -| `GET` | `/audit` | List audit log (query: `offset`, `limit`) | -| `POST` | `/scan` | Trigger directory scan (`{"path": "/..."}` or `{"path": null}` for all roots) | - - +[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