From 7c32f8a87889c8fdb8637243fd540061ea1a8539 Mon Sep 17 00:00:00 2001 From: Sam Anthony Date: Sat, 7 Mar 2026 11:45:19 -0500 Subject: doc: simplify architecture, some notes Got rid of client-side 9p, which was just silly bloat. Using HTTP exclusively on the client side now, with htmx. Combined auth and api servers into monolithic buthd, which translates http/9p between client and backend 9p servers. Added some implementation and security notes, and part of shopfs. --- doc/api.md | 19 +++++++++++++++++++ 1 file changed, 19 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..8436144 --- /dev/null +++ b/doc/api.md @@ -0,0 +1,19 @@ + +# API usage + +This document describes how a client uses buthd's API once he's [logged in](auth) (has a session cookie). + +An example: adding an item to the shopping cart. +- Client `GET`s `shop./foo.html` + - Includes session cookie in request +- httpd returns static page and scripts +- Client interacts with page, e.g. presses "add to cart" +- htmx `POST`s a form to `api./cart` containing `` and `` + - Includes the session cookie in the request +- `buthd` receives the request, extracts the session ID from the session cookie +- `buthd` uses the session ID to look up the user's username by reading `/sessions//user` from [[authfs]] +- `buthd` adds `` units of `` to ``'s cart using [[shopfs]] + +Other parts of the API behave similarly: client posts to buthd, buthd uses 9P servers to complete the request. + +TODO: define and document all of buthd's HTTP endpoints -- cgit v1.2.3