Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions PRODUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,10 @@ web

## Users

Three audiences, weighted equally. The site routes each to its own path rather than picking one:
The home page is written for a general technical reader first: someone who arrives from a link and has never
met the protocol. It states the problem and the idea in plain words before the mechanism, and names the
technology once for the reader who wants it. The docs pages serve three audiences, weighted equally, and the
home page routes each to its own path rather than picking one:

- **Protocol reviewers**: IETF participants, HTTP and API-standards people, security reviewers. They read the
draft to judge its rigour and send critique.
Expand Down Expand Up @@ -76,7 +79,7 @@ in REST:ACT the API's clients deploy it, it runs as each caller, and it is charg

- The draft and its companion documents (the extension drafts, registries), rendered under `/spec/`.
- Interactive explanations: `AnatomyDemo.astro` (four requests against `notes/42`), `ResolutionWalk.astro`.
- Real behaviour from restactd: status codes 408/429/507, default limits, the `/.well-known/restact` document,
- Real behaviour from restactd: status codes 504/429/507, default limits, the `/.well-known/restact` document,
verbatim shell sessions.
- restactd, restact-conformance, verbsmith, restact-sdk and the agent plugins exist and are linked.
- **Absent, never to be invented:** adopters, users, testimonials, benchmarks, other implementations, IETF
Expand Down
4 changes: 3 additions & 1 deletion src/pages/how-it-works.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: ../layouts/MdPage.astro
title: How REST:ACT works
description: A REST:ACT server is a tree of objects addressed by path. Each object has data, read and written with the standard HTTP methods, and verbs, uploaded programs addressed with a colon and invoked over HTTP.
description: A REST:ACT server holds objects at addresses, much as a disk holds files in folders. Each object has data, which you read and write with ordinary HTTP requests. It can also have verbs, small uploaded programs you run by adding a colon and the verb’s name to the object’s address.
summary: A REST:ACT server is a tree of objects addressed by path. Each object has data, read and written with HTTP, and verbs, uploaded programs called over HTTP.
chips:
- Explanatory
Expand All @@ -17,6 +17,8 @@ import ResolutionWalk from '../components/ResolutionWalk.astro';
import InRestactd from '../components/InRestactd.astro';
import { RESTACTD_DOCS } from '../site.config';

This page shows how the server finds the verb a request names, how a function differs from an action, and what a verb is allowed to reach.

## Objects, data and verbs

An object such as `/animals/dogs/fido` has data, its JSON representation, and verbs addressed off it. The path hierarchy is a single-inheritance chain: fido's ancestors are dogs, animals and the root.
Expand Down
22 changes: 11 additions & 11 deletions src/pages/index.astro
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,12 @@ const abstract = [
'Each verb is a WebAssembly component. The server runs it in a sandbox, by default with the permissions of whoever calls it, and stops it when it runs out of time or memory.',
];

/* One next step for each of the three readers, named as the reader groups at the close name them,
then the reference server, which all three can use. */
/* One next step for each of the three readers, then the reference server, which all three can use.
Each link carries the same name here and in the reader groups at the close: one name per page. */
const next = [
{ label: 'Review the protocol', href: DRAFT_URL },
{ label: 'Implement a server', href: '/spec/' },
{ label: 'Write and call verbs', href: '/start/' },
{ label: 'Read the draft', href: DRAFT_URL },
{ label: 'Specification overview', href: '/spec/' },
{ label: 'Get started', href: '/start/' },
{ label: 'Run the reference server', href: '/restactd/' },
];

Expand All @@ -55,25 +55,25 @@ const paths = {
{
reader: 'Reviewing the protocol',
links: [
{ label: 'How it works', href: '/how-it-works/', body: 'Objects, verbs and how a request finds the verb it names, step by step.' },
{ label: 'Read the draft', href: DRAFT_URL, body: 'Addressing, method semantics, capabilities, limits, authorization and security considerations.' },
{ label: 'Specification overview', href: '/spec/', body: 'A section-by-section map of the draft, marked core or optional.' },
{ label: 'Security model', href: '/security/', body: 'The threat model and how the draft answers it.' },
],
},
{
reader: 'Implementing a server',
links: [
{ label: 'How it works', href: '/how-it-works/', body: 'Addressing and verb resolution, step by step.' },
{ label: 'restact-conformance', href: RESTACTD_DOCS.conformance, body: 'Black-box tests for any server, run against the features it advertises.' },
{ label: 'restactd', href: '/restactd/', body: 'The reference server, in Rust on Wasmtime: what it implements, its documentation and its source.' },
{ label: 'Specification overview', href: '/spec/', body: 'A section-by-section map of the draft, marked core or optional.' },
{ label: 'Test a server', href: RESTACTD_DOCS.conformance, body: 'restact-conformance sends black-box tests to any server, using the features it advertises.' },
{ label: 'Run the reference server', href: '/restactd/', body: 'restactd, in Rust on Wasmtime: what it implements, its documentation and its source.' },
],
},
{
reader: 'Writing and calling verbs',
links: [
{ label: 'Get started', href: '/start/', body: 'Run restactd locally and deploy a first verb in JavaScript, Python or Rust.' },
{ label: 'restact mcp', href: GITHUB.mcp, body: 'Serves a REST:ACT host’s verbs as MCP tools.' },
{ label: 'restact-sdk', href: GITHUB.sdk, body: 'A Rust crate for writing verbs.' },
{ label: 'Call verbs from an AI agent', href: GITHUB.mcp, body: 'restact mcp serves a REST:ACT host’s verbs as MCP tools.' },
{ label: 'Write verbs in Rust', href: GITHUB.sdk, body: 'restact-sdk, a Rust crate for writing verbs.' },
],
},
],
Expand Down
Loading