# api-dev

Adopt this skill: https://proskills.md/skills/other/albertdobmeyer-opentrapp-workloads-skills-skills-api-dev

Page: https://proskills.md/skills/other/albertdobmeyer-opentrapp-workloads-skills-skills-api-dev
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: workloads/skills/skills/api-dev/SKILL.md
size: 8003
upstream: https://github.com/albertdobmeyer/opentrapp/blob/main/workloads/skills/skills/api-dev/SKILL.md

````text
---
name: api-dev
version: 1.0.0
description: Scaffold, test, document, and debug REST and GraphQL APIs. Use when the user needs to create API endpoints, write integration tests, generate OpenAPI specs, test with curl, mock APIs, or troubleshoot HTTP issues.
metadata: {"clawdbot":{"emoji":"🔌","requires":{"anyBins":["curl","node","python3"]},"os":["linux","darwin","win32"]}}
---

# API Development

Build, test, document, and debug HTTP APIs from the command line. Covers the full API lifecycle: scaffolding endpoints, testing with curl, generating OpenAPI docs, mocking services, and debugging.

## When to Use

- Scaffolding new REST or GraphQL endpoints
- Testing APIs with curl or scripts
- Generating or validating OpenAPI/Swagger specs
- Mocking external APIs for development
- Debugging HTTP request/response issues
- Load testing endpoints

## Testing APIs with curl

### GET requests

```bash
# Basic GET
curl -s https://api.example.com/users | jq .

# With headers
curl -s -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://api.example.com/users | jq .

# With query params
curl -s "https://api.example.com/users?page=2&limit=10" | jq .

# Show response headers too
curl -si https://api.example.com/users
```

### POST/PUT/PATCH/DELETE

```bash
# POST JSON
curl -s -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Alice", "email": "alice@example.com"}' | jq .

# PUT (full replace)
curl -s -X PUT https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Updated", "email": "alice@example.com"}' | jq .

# PATCH (partial update)
curl -s -X PATCH https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice V2"}' | jq .

# DELETE
curl -s -X DELETE https://api.example.com/users/123

# POST form data
curl -s -X POST https://api.example.com/upload \
  -F "file=@document.pdf" \
  -F "description=My document"
```

### Debug requests

```bash
# Verbose output (see full request/response)
curl -v https://api.example.com/health 2>&1

# Show only response headers
curl -sI https://api.example.com/health

# Show timing breakdown
curl -s -o /dev/null -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nFirst byte: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://api.example.com/health

# Follow redirects
curl -sL https://api.example.com/old-endpoint

# Save response to file
curl -s -o response.json https://api.example.com/data
```

## API Test Scripts

### Bash test runner

```bash
#!/bin/bash
# api-test.sh - Simple API test runner
BASE_URL="${1:-http://localhost:3000}"
PASS=0
FAIL=0

assert_status() {
  local method="$1" url="$2" expected="$3" body="$4"
  local args=(-s -o /dev/null -w "%{http_code}" -X "$method")
  if [ -n "$body" ]; then
    args+=(-H "Content-Type: application/json" -d "$body")
  fi
  local status
  status=$(curl "${args[@]}" "$BASE_URL$url")
  if [ "$status" = "$expected" ]; then
    echo "PASS: $method $url -> $status"
    ((PASS++))
  else
    echo "FAIL: $method $url -> $status (expected $expected)"
    ((FAIL++))
  fi
}

assert_json() {
  local url="$1" jq_expr="$2" expected="$3"
  local actual
  actual=$(curl -s "$BASE_URL$url" | jq -r "$jq_expr")
  if [ "$actual" = "$expected" ]; then
    echo "PASS: GET $url | jq '$jq_expr' = $expected"
    ((PASS++))
  else
    echo "FAIL: GET $url | jq '$jq_expr' = $actual (expected $expected)"
    ((FAIL++))
  fi
}

# Health check
assert_status GET /health 200

# CRUD tests
assert_status POST /api/users 201 '{"name":"Test","email":"test@test.com"}'
assert_status GET /api/users 200
assert_json /api/users '.[-1].name' 'Test'
assert_status DELETE /api/users/1 204

# Auth tests
assert_status GET /api/admin 401
assert_status GET /api/admin 403  # with wrong role

echo ""
echo "Results: $PASS passed, $FAIL failed"
[ "$FAIL" -eq 0 ] && exit 0 || exit 1
```

### Python test runner

```python
#!/usr/bin/env python3
"""api_test.py - API integration test suite."""
import json, sys, urllib.request, urllib.error

BASE = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:3000"
PASS = FAIL = 0

def request(method, path, body=None, headers=None):
    """Make an HTTP request, return (status, body_dict, headers)."""
    url = f"{BASE}{path}"
    data = json.dumps(body).encode() if body else None
    hdrs = {"Content-Type": "application/json", "Accept": "application/json"}
    if headers:
        hdrs.update(headers)
    req = urllib.request.Request(url, data=data, headers=hdrs, method=method)
    try:
        resp = urllib.request.urlopen(req)
        body = json.loads(resp.read().decode()) if resp.read() else None
    except urllib.error.HTTPError as e:
        return e.code, None, dict(e.headers)
    return resp.status, body, dict(resp.headers)

def test(name, fn):
    """Run a test function, track pass/fail."""
    global PASS, FAIL
    try:
        fn()
        print(f"  PASS: {name}")
        PASS += 1
    except AssertionError as e:
        print(f"  FAIL: {name} - {e}")
        FAIL += 1

def assert_eq(actual, expected, msg=""):
    assert actual == expected, f"got {actual}, expected {expected}. {msg}"

# --- Tests ---
print(f"Testing {BASE}\n")

test("GET /health returns 200", lambda: (
    assert_eq(request("GET", "/health")[0], 200)
))

test("POST /api/users creates user", lambda: (
    assert_eq(request("POST", "/api/users", {"name": "Test", "email": "t@t.com"})[0], 201)
))

test("GET /api/users returns array", lambda: (
    assert_eq(type(request("GET", "/api/users")[1]), list)
))

test("GET /api/notfound returns 404", lambda: (
    assert_eq(request("GET", "/api/notfound")[0], 404)
))

print(f"\nResults: {PASS} passed, {FAIL} failed")
sys.exit(0 if FAIL == 0 else 1)
```

## OpenAPI Spec Generation

### Generate from existing endpoints

```bash
# Scaffold an OpenAPI 3.0 spec from curl responses
# Run this, then fill in the details
cat > openapi.yaml << 'EOF'
openapi: "3.0.3"
info:
  title: My API
  version: "1.0.0"
  description: API description here
servers:
  - url: http://localhost:3000
    description: Local development
paths:
  /health:
    get:
      summary: Health check
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
  /api/users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Validation error
  /api/users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Not found
components:
  schemas:
    User:
      type: object
      prop
````

## File: README.md
upstream: https://github.com/albertdobmeyer/opentrapp/blob/main/README.md

````text
<p align="center">
  <img src="app/public/logo-banner.png" alt="OpenTrApp" width="600"/>
</p>

# OpenTrApp

[![CI](https://github.com/albertdobmeyer/opentrapp/actions/workflows/ci.yml/badge.svg)](https://github.com/albertdobmeyer/opentrapp/actions/workflows/ci.yml)
[![CodeQL](https://github.com/albertdobmeyer/opentrapp/actions/workflows/codeql.yml/badge.svg)](https://github.com/albertdobmeyer/opentrapp/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/albertdobmeyer/opentrapp/badge)](https://scorecard.dev/viewer/?uri=github.com/albertdobmeyer/opentrapp)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12755/badge)](https://www.bestpractices.dev/projects/12755)
[![License: MIT](https://img.shields.io/badge/License-MIT-009966.svg)](LICENSE)

> **Status (2026-06-26):** The **lean-down campaign has shipped on `main`.** The Tauri/WebKitGTK desktop GUI is **deleted**, so OpenTrApp is now the lean, headless **`opentrapp-daemon`** plus an **on-demand browser projection** (the loopback `viewer-server`, rendering in your existing browser only while a dashboard is open), and the build is **GTK-free** (the 19 GTK3 advisories cleared; `Cargo.lock` has 0 `tauri`/`wry`/`webkit` entries). The perimeter itself is lean end to end: the credential-holding proxy is now a **15 MB Go chokepoint** (`elazarl/goproxy`) that replaced the leaky Python mitmproxy — putting the Python interpreter out of the keys-holding container ([ADR-0026](docs/adr/0026-vault-proxy-replacement-evaluation.md)) — and **every workload base is Alpine** (vault-skills 233→72 MB, vault-social 153→74 MB). The new proxy's **full live-boundary self-test is still pending** before it is claimed end-to-end correct. Cross-platform **installers for the new architecture are pending** ([cargo-dist, ADR-0023](docs/adr/0023-distribution-and-packaging.md)); until they ship, the new build runs **from source**, and the **last tagged release ([v0.8.0](https://github.com/albertdobmeyer/opentrapp/releases/latest)) is still the previous Tauri desktop app**. The CLI-first / registry direction continues per [ADR-0020](docs/adr/0020-product-identity-and-distribution.md). See [`CLAUDE.md`](CLAUDE.md) for the full target-versus-current framing.

A safer way to run an autonomous CLI agent on your own computer. OpenTrApp wraps the agent in a security perimeter built on two ideas. **Privilege separation:** no single container holds both your API keys and internet access, so a compromised agent can reach neither directly. **Supply-chain defense:** every skill the agent loads is vetted in isolation before it can reach the agent, because a malicious skill runs as part of the agent's own reasoning. Open-source under MIT.

It is pre-wired for [OpenClaw](https://www.getopenclaw.ai); the product is the perimeter itself, and the GUI is one optional, on-demand projection of it (see status above). The perimeter is agent-agnostic by design; opencode, Claude Code, and other CLI agents are candidates for support.

For a one-page explainer of how the perimeter works (one contained agent, two guards around it), see [`docs/perimeter-explained.md`](docs/perimeter-explained.md). The full architecture, threat model, and per-component capabilities are in [`docs/trifecta.md`](docs/trifecta.md).

**Author:** [@albertdobmeyer](https://github.com/albertdobmeyer) · **Public landing page:** [opentrapp.com](https://opentrapp.com)

---

## Try it, lowest commitment first

You do not have to adopt the whole perimeter to get value out of this.

**1. Scan your agent's skills in CI (one line, fully offline, no model).** The skill scanner runs as a GitHub Action, so any repository can gate its skills or plugins against malware and prompt injection before they ship:

```yaml
- uses: albertdobmeyer/opentrapp/actions/skill-scan@skill-scan-v1
  with: { path: ./skills }
```

Findings land in your repository's Security tab, and a finding fails the job. Details in [`actions/skill-scan/`](actions/skill-scan/).

**2. Scan a skill locally before you install it.** From a clone of this repo, the same offline check runs as a one-line pre-install gate, with no global install needed:

```bash
workloads/skills/skill scan ./that-plugin --strict || echo "blocked by the skill firewall"
```

**3. Run the full perimeter.** The latest tagged release ([v0.8.0](https://github.com/albertdobmeyer/opentrapp/releases/latest)) ships the previous Tauri desktop app with a setup wizard — the end-to-end containment story. The de-Tauri build on `main` (headless `opentrapp-daemon` + an on-demand browser dashboard) runs from source today; signed cross-platform installers for it are pending ([cargo-dist, ADR-0023](docs/adr/0023-distribution-and-packaging.md)).

---

## Purpose

Autonomous CLI agents, such as [OpenClaw](https://www.getopenclaw.ai), execute shell commands, read files, and load skills from third-party registries. Run with default settings, the agent has the same operating-system privileges as the user. The ClawHavoc study (2026-Q1) of one such registry classified 11.9% of published skills as malicious (341 of 2,857). OpenTrApp wraps any such agent in a defense-in-depth perimeter to reduce the impact of agent compromise, malicious skills, and prompt-injection attacks. The shipped integration is OpenClaw, and the perimeter is designed to extend to other CLI agents.

Reasoning is delegated to the agent's vendor API (Anthropic's, for OpenClaw); only the agent's execution layer (file work, tool calls, skill invocations) is local.

<p align="center">
  <img src="article/assets/perimeter-flow.svg" alt="A request flows from the caged agent through the key-injecting proxy and the network filter to the allowlisted internet. The proxy holds the keys but has no internet route; the egress filter has the internet route but holds no keys." width="820"/>
</p>

<p align="center"><em>Privilege separation in one picture: the proxy holds your keys but has no route to the internet, and the egress filter has the route but never sees your keys.</em></p>

## Values

These are the principles that shape every design and product decision in this project. They are written down because the alternative, leaving them implicit, is how projects drift.

- **Safety-first, safety-always.** The perimeter exists because autonomous agents are powerful and powerful tools fail in expensive ways. Every architectural choice is evaluated against its containment effect first; convenience second. Defaults err on the restrictive side and are documented when they do.
- **Honest about residual risk.** The application can never claim to make running an autonomous agent absolutely safe. It raises the cost of compromise via defense-in-depth and is open about the gaps that remain. [**What this protects against, and what it doesn't**](docs/what-this-protects.md) is the plain-language summary; the [threat model](docs/threat-model.md) names every gap; the [whitepaper](docs/whitepaper.md) explains them.
- **Agent-agnostic, community-driven.** The perimeter is not coupled to any single CLI agent. The reference deployment is OpenClaw because OpenClaw exists today; the architecture is designed to extend to others. Contributions that broaden compatibility are welcomed.
- **Transparency over marketing.** No tracking, no telemetry, no proprietary blobs. Every dependency, every container layer, every external request is documentable from the source tree. Reproducibility steps are in [`docs/reproduce.md`](docs/reproduce.md).
- **Shared for the safety of the commons.** This project is MIT-licensed and developed in the open. Security research findings, hardening recipes, and threat-model deltas land in the repo where everyone running an autonomous CLI agent can benefit, not in private channels.
- **Lean by design, runs on modest hardware.** OpenTrApp is a lean background app. The full perimeter and its boundary self-test must run on a 7.2 GB laptop, the hard floor; idle auto
````
