docs: clarify wording around API split
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I864882c5a22424cd6c8c320627fe9f006a6a6964
This commit is contained in:
parent
3ccddce7fd
commit
c535650f45
1 changed files with 7 additions and 67 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue