`api_scaffold`

Generate a Yichus-first Bosatsu API module: structs, Yichus/Access rules, owner-scoped or public handlers, and a Yichus/Service routing table, plus a matching Yichus/Frontend::FrontendSpec (frontendSource) for api_frontend. The result compiles and verifies; edit it, then api_verify.

Kind: Scaffold. Origin: Yichus/Mcp::catalog.

CLI: none — the API scaffold (ApiScaffold) has no dedicated CLI subcommand; `service generate` plans CRUD endpoints for a service, a different generator.

Parameters

package_name (required, string) — Bosatsu package, PascalCase segments separated by slashes, e.g. My/Notes/Api
service_name (required, string) — snake_case service name, e.g. notes
resources (required, array) — JSON array of {name, fields:[{name,type}], policy}. type is String, Int, or Bool. policy is owner or public.

Example

This response was produced by calling this tool with the displayed request when these docs were generated. Analysis examples use the owner-scoped notes specimen; scaffold examples supply a resource specification.

Request

{
  "package_name": "Demo/Service/TasksApi",
  "service_name": "tasks",
  "resources": [
    {
      "name": "task",
      "policy": "owner",
      "fields": [
        {
          "name": "title",
          "type": "String"
        }
      ]
    }
  ]
}

Response

{
  "ok": true,
  "tool": "api_scaffold",
  "fileName": "tasks_api.bosatsu",
  "source": "package Demo/Service/TasksApi\n\n# Generated by the Yichus API scaffolder. Edit freely: safety is\n# re-proven from the compiled IR by `api_verify`, not assumed from\n# this template.\n\nfrom Yichus/IO import IO, flat_map\nfrom Yichus/Access import Principal, AccessRule, AccessSpec, OwnerScoped\nfrom Yichus/Data import Db, Table, table, db_read, db_write, db_delete\nfrom Yichus/Service import handler, route, service_def, ReadPerm, WritePerm, DeletePerm\n\nexport (tasks_api, access_rules, Task())\nexposes (Yichus/Access, Yichus/Service)\n\nstruct Task(title: String)\n\n# The declared access surface. `api_verify` proves each rule against\n# the handlers below — and keeps proving it as this file is edited.\naccess_rules = AccessSpec([\n  AccessRule(\"tasks\", OwnerScoped),\n])\n\n# Tasks are owner-scoped: one row per user, keyed by exactly\n# Principal.user_id, holding that user's list. The analyzer proves no\n# handler can reach another caller's row.\ndef tasks_table(db: Db) -> Table[List[Task]]:\n  table(db, \"tasks\")\n\ndef list_tasks(db: Db, p: Principal) -> IO[List[Task]]:\n  Principal(uid, _) = p\n  db_read(tasks_table(db), uid)\n\ndef put_tasks(db: Db, p: Principal, items: List[Task]) -> IO[List[Task]]:\n  Principal(uid, _) = p\n  db_write(tasks_table(db), uid, items)\n\n# Read-modify-write on the caller's row: `api_verify` reports this as\n# transaction-required when deploying multiple instances on one DB.\ndef add_task(db: Db, p: Principal, item: Task) -> IO[List[Task]]:\n  Principal(uid, _) = p\n  items <- flat_map(db_read(tasks_table(db), uid))\n  db_write(tasks_table(db), uid, [item, *items])\n\ndef clear_tasks(db: Db, p: Principal) -> IO[Unit]:\n  Principal(uid, _) = p\n  db_delete(tasks_table(db), uid)\n\ntasks_api = service_def(\n  \"tasks\",\n  [\n    route(\"/tasks\", handler(\"list_tasks\", list_tasks), [ReadPerm(\"tasks\")]),\n    route(\"/tasks/put\", handler(\"put_tasks\", put_tasks), [WritePerm(\"tasks\")]),\n    route(\"/tasks/add\", handler(\"add_task\", add_task), [ReadPerm(\"tasks\"), WritePerm(\"tasks\")]),\n    route(\"/tasks/clear\", handler(\"clear_tasks\", clear_tasks), [DeletePerm(\"tasks\")]),\n  ]\n)\n",
  "frontendFileName": "tasks_app.bosatsu",
  "frontendSource": "package Demo/Service/TasksApi/Frontend\n\n# Generated by the Yichus API scaffolder: screens over the scaffolded\n# routes. Edit titles and drop views freely; `api_frontend` re-proves\n# every path against the route table. Compile together with\n# tasks_api.bosatsu.\n\nfrom Bosatsu/Predef import List\nfrom Yichus/Frontend import View, FrontendSpec, ListView, Form, Action\n\nexport (tasks_app)\nexposes Yichus/Frontend\n\ntasks_app = FrontendSpec(\n  \"Tasks\",\n  [\n    View(\"/tasks\", \"Your tasks\", ListView),\n    View(\"/tasks/put\", \"Replace tasks\", Form),\n    View(\"/tasks/add\", \"Add task\", Form),\n    View(\"/tasks/clear\", \"Clear tasks\", Action),\n  ]\n)\n",
  "note": "source is the API module; frontendSource is a matching Yichus/Frontend::FrontendSpec. Compile them together and pass both files to api_verify and api_frontend."
}

Run tools in the browser: api-mcp.html?webmcp=1.

Read the result according to this tool’s scope: static checks, bounded execution checks, and descriptive diagrams answer different questions. A successful call is not a general approval of the program. The safety and permissions guide compares the checks and provides editable ownership, guard, and role examples.