From 7ded0f89080275d9a59e5155e1459ad7bf28509b Mon Sep 17 00:00:00 2001
From: metamuffin <metamuffin@disroot.org>
Date: Thu, 25 Jan 2024 19:04:29 +0100
Subject: more doc + api

---
 doc/api.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 doc/api.md

(limited to 'doc/api.md')

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.
-- 
cgit v1.2.3-70-g09d2