NotAShelf/pinakes
1
0
Fork 0
Code Issues 6 Pull requests Projects Releases Packages Wiki Activity Actions

docs: clarify wording around API split

Browse source 
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
1 changed files with 7 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

74
docs/README.md
View file

@ -132,19 +132,18 @@ $ cargo run -p pinakes-ui
### Extending Pinakes ### 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 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 feasible to maintain all features in one gigantic repository without taking on
an immense technical debt. To avoid this kind of resource mismanagement while an immense technical debt. To avoid this kind of resource mismanagement while
still allowing for _all_ kinds of extension, Pinakes features two features at still allowing for _all_ kinds of extension, Pinakes features two features at
your convenience: your convenience:
- Server API Routes - REST API Routes
- Plugin API - Plugin API
### API ### REST API
[REST API documentation]: ./api.md
There exists a comprehensive UI for the server component that you may query 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`. 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 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 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 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. interact with the API.
#### Media ### Plugin API
| Method | Path | Description | [Plugin API documentation]: ./plugins.md
| -------- | -------------------- | ------------------------------------- |
| `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-->
The other method, which is by far the most powerful but also perhaps the least 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 polished as of writing is the **plugin system**. This is designed as a means of