From 8f2cea5567ef205d7ceeea6bc6cbf4e729e3fba4 Mon Sep 17 00:00:00 2001
From: Marc Villain <marc.villain@epita.fr>
Date: Tue, 3 Nov 2026 07:23:44 +0100
Subject: [PATCH] docs: calling restloom from your own code, without HTTP

---
 docs/adapters.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/adapters.md b/docs/adapters.md
index 08f7fa0..c1b7ba8 100644
--- a/docs/adapters.md
+++ b/docs/adapters.md
@@ -43,6 +43,35 @@ import { restloom } from '@crudy/restloom-express';
 app.use('/api', express.json(), restloom(rest, { context: (req) => req.user }));
 ```
 
+## From your own code
+
+Your backend never needs to call its own API over HTTP. `rest.handle` runs a request in the same process, through the same checks, hooks and row security as a client's, and gives the answer back as data:
+
+```ts
+const { status, body: todos } = await rest.handle({
+    method: 'GET',
+    path: '/todos',
+    query: new URLSearchParams('select=id,name,owner(name)&status=eq.open'),
+    headers: {},
+    context: currentUser,
+});
+```
+
+A write passes its body as an object, and header names in lower case:
+
+```ts
+const { status, body } = await rest.handle({
+    method: 'POST',
+    path: '/tags',
+    query: new URLSearchParams('select=id,name'),
+    headers: { prefer: 'return=representation' },
+    body: { id: 8, name: 'garden' },
+    context: currentUser,
+});
+```
+
+A call from your code is not trusted more than a client's: `authorize` and `scope` receive its `context` like any other. Pass the user you act for, or a context your hooks recognise as a background job. Check `status` rather than catching: `handle` never throws, and an error answers its code in `body.error`.
+
 ## Your own routes
 
 A host that registers every route itself, to attach its own permissions or documentation to each, calls `rest.handle` from those routes. That is how crudy mounts restloom: each declared route checks its permission, then hands the request to restloom.