more doc + api

1 files changed, 55 insertions, 0 deletions

diff --git a/doc/api.md b/doc/api.md
new file mode 100644
index 0000000..0b89be5
--- /dev/null
+++ b/doc/api.md
@@ -0,0 +1,55 @@
+# Jellything API
+
+Most endpoints require the `Accept` header to be present and set to
+`application/json` and `image/avif` respectively. Any endpoint returning JSON, will report errors with an
+object containing error string in the `error` key. Routes marked with `*`
+require authentification.
+
+The `jellyclient` crate already implements most API functionality. The
+`jellycommon` crate provides useful structs for deserializing data (also
+reexported in jellyclient).
+
+```toml
+# Cargo.toml
+[depedencies]
+jellyclient = { git = "https://codeberg.org/metamuffin/jellything.git" }
+```
+
+## General
+
+### GET `/api/version`
+Returns API version number.
+
+### POST `/api/create_session`
+Request body contains JSON with keys `username`, `password`, `expire` (in
+seconds) and `drop_permissions` (a list of permissions, that this session cannot
+use). The Response contains the session cookie as a string in JSON.
+
+### GET* `/n/<id>`
+Request a library node (either a directory or item). Returns it as `NodePublic`.
+
+### GET* `/n/<id>/extended`
+Request extended informationf for library node. Returns it as `ExtendedNode`.
+
+## Assets
+
+All asset endpoints redirect to the asset that you need. Returned images are
+coded with AVIF. The `width` parameter is the width of the resolution you want to image to be.
+
+> [!WARNING]
+> The actual returned resolution must not be exactly what you requested.
+
+### GET* `/n/<id>/asset?<role>&<width>`
+Where `role` is one of `backdrop` or `poster` and 
+
+### GET* `/n/<id>/thumbnail?<t>&<width>`
+Returns a single frame from some track video of the media at a given time `t`. 
+
+### GET* `/n/<id>/person/<index>/asset?<group>&<width>`
+Returns headshot of a person from that node.
+
+## Stream
+
+### GET* `/stream/<id>?<format>&<index>&<profile>&<index>&<tracks>&<webm>`
+Responds with the stream directly or a redirect to the actual source in case of
+federation.