diff options
| author | Sam Anthony <sam@samanthony.xyz> | 2026-03-07 11:45:19 -0500 |
|---|---|---|
| committer | Sam Anthony <sam@samanthony.xyz> | 2026-03-07 11:45:19 -0500 |
| commit | 7c32f8a87889c8fdb8637243fd540061ea1a8539 (patch) | |
| tree | fe5b5b42f3cfe74e755cf57419b7f3d3b6dd89bb /doc/api.md | |
| parent | 36381d86c6a690a7870ce360dad63be333361447 (diff) | |
| download | buth-7c32f8a87889c8fdb8637243fd540061ea1a8539.zip | |
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.
Diffstat (limited to 'doc/api.md')
| -rw-r--r-- | doc/api.md | 19 |
1 files changed, 19 insertions, 0 deletions
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 `<sku>` and `<quantity>` + - 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/<id>/user` from [[authfs]] +- `buthd` adds `<quantity>` units of `<sku>` to `<username>`'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 |