From d73096c553498d6f86303a55e61981bf3ef273eb Mon Sep 17 00:00:00 2001
From: Ilya Zlobintsev <ilya.zl@protonmail.com>
Date: Sat, 25 Feb 2023 14:31:51 +0200
Subject: [PATCH] feat: add API information

---
 API.md    | 42 ++++++++++++++++++++++++++++++++++++++++++
 README.md |  3 +++
 2 files changed, 45 insertions(+)
 create mode 100644 API.md

diff --git a/API.md b/API.md
new file mode 100644
index 0000000..69366dd
--- /dev/null
+++ b/API.md
@@ -0,0 +1,42 @@
+# Description
+
+The LACT Daemon exposes a JSON API over a unix socket, available on `/var/run/lactd.sock`. You can configure who has access to the socket in `/etc/lact/config.yaml` in the `daemon.admin_groups` field.
+
+The API expects newline-separated JSON objects, and returns a JSON object for every request.
+
+The general format of requests looks like:
+```
+{"command": "command_name", "args": {}}
+```
+Note that the type of `args` depends on the specific request, and may be ommited in some cases.
+
+The response looks like this:
+```
+{"status": "ok|error", "data": {}}
+```
+Same as `args` in requests, `data` can be of a different type and may not be present depending on the specific request.
+
+You can try sending commands to socket interactively with `ncat`:
+```
+echo '{"command": "list_devices"}' | ncat -U /run/lactd.sock
+```
+Example response:
+```
+{"status":"ok","data":[{"id":"1002:687F-1043:0555-0000:0b:00.0","name":"Vega 10 XL/XT [Radeon RX Vega 56/64]"}]}
+```
+
+# Commands
+
+For the full list of available commands and responses, you can look at the source code of the schema: [requests](lact-schema/src/request.rs), [the basic response structure](lact-schema/src/response.rs) and [all possible types](lact-schema/src/lib.rs).
+
+It should also be fairly easy to figure out the API by trial and error, as the error message are quite verbose:
+
+```
+echo '{"command": "test"}' | ncat -U /run/lactd.sock
+
+{"status":"error","data":"Failed to deserialize request: unknown variant `test`, expected one of `ping`, `list_devices`, `system_info`, `device_info`, `device_stats`, `device_clocks_info`, `set_fan_control`, `set_power_cap`, `set_performance_level`, `set_clocks_value` at line 1 column 18"}
+```
+
+# Rust
+
+If you want to connect to the socket from a Rust program, you can simply import either the `lact-client` or `lact-schema` (if you want to write a custom client) crates from this repository.
\ No newline at end of file
diff --git a/README.md b/README.md
index cf150c8..d4e665b 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,9 @@ sudo systemctl enable --now lactd
 ```
 You can now use the application.
 
+# API
+There is an API available over a unix socket. See [here](API.md) for more information.
+
 # CLI
 
 There is also a cli available.