# Graysurf Agent Kit REST API Testing

> REST API Testing

- Skill: `tomevault-io/graysurf-agent-kit-rest-api-testing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/graysurf-agent-kit-rest-api-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/graysurf-agent-kit-rest-api-testing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/graysurf-agent-kit-rest-api-testing

---


# REST API Testing

## Contract

Prereqs:

- `api-rest` available on `PATH` (install via `brew install nils-cli`).
- `jq` recommended for pretty-printing/assertions (optional).
- `setup/rest/` exists (or bootstrap from template) with requests and optional endpoint/token presets.

Inputs:

- Request file path: `setup/rest/requests/<name>.request.json`.
- Optional flags/env (runner): `--env`, `--url`, `--token`, `--config-dir`, `--no-history` (plus `REST_URL`, `ACCESS_TOKEN`,
  `REST_JWT_VALIDATE_ENABLED`, `REST_JWT_VALIDATE_STRICT`, `REST_JWT_VALIDATE_LEEWAY_SECONDS`).

Outputs:

- Response JSON (or raw response) printed to stdout; errors printed to stderr.
- Optional history file under `setup/rest/.rest_history` (gitignored; disabled via `--no-history`).
- Optional markdown report via `api-rest report`.

Exit codes:

- `0`: request completed successfully (and assertions, if present, passed)
- non-zero: invalid inputs/missing files/http error/assertion failure

Failure modes:

- Missing `curl`, invalid request JSON, or missing endpoint configuration (`REST_URL` / endpoints env).
- Auth missing/invalid (`ACCESS_TOKEN` / token profile) causing 401/403.
- Network/timeout/connection failures.

## Goal

Make REST API calls reproducible and CI-friendly via:

- `setup/rest/requests/*.request.json` (request + optional `expect` assertions)
- `setup/rest/endpoints.env` (+ optional `endpoints.local.env`)
- `setup/rest/tokens.env` (+ optional `tokens.local.env`)
- `setup/rest/prompt.md` (optional, committed; project context for LLMs)

## TL;DR (fast paths)

Call an existing request (JSON only):

```bash
api-rest call \
  --env local \
  setup/rest/requests/<request>.request.json \
| jq .
```

If the endpoint requires auth, pass a token profile (from `setup/rest/tokens.local.env`) or use `ACCESS_TOKEN`:

```bash
# Token profile (requires REST_TOKEN_<NAME> to be non-empty in setup/rest/tokens.local.env)
api-rest call --env local --token default setup/rest/requests/<request>.request.json | jq .

# Or: one-off token (useful for CI)
REST_URL="https://<host>" ACCESS_TOKEN="<token>" \
  api-rest call --url "$REST_URL" setup/rest/requests/<request>.request.json | jq .
```

Replay the last run (history):

```bash
api-rest history --command-only
```

Generate a report (includes a replayable `## Command` by default):

```bash
api-rest report \
  --case "<test case name>" \
  --request setup/rest/requests/<request>.request.json \
  --env local \
  --run
```

Generate a report from a copied `api-rest`/`rest.sh` command snippet (no manual rewriting):

```bash
api-rest report-from-cmd '<paste an api-rest/rest.sh command snippet>'
```

## Flow (decision tree)

- If `setup/rest/prompt.md` exists → read it first for project-specific context.
- No `setup/rest/` yet → bootstrap from template:
  - `cp -R "$AGENT_HOME/skills/tools/testing/rest-api-testing/assets/scaffold/setup/rest" setup/`
- Have request file → run with `api-rest call`.
- Need a markdown report → use `api-rest report --run` (or `--response`).

## Notes (defaults)

- History is on by default: `setup/rest/.rest_history` (gitignored); one-off disable with `--no-history` (or `REST_HISTORY_ENABLED=false`).
- Requests can embed CI-friendly assertions:
  - `expect.status` (integer; required when `expect` is present)
  - `expect.jq` (optional; evaluated with `jq -e` against the JSON response)
- Reports redact common secret-like fields by default (e.g. `Authorization`, `Cookie`, `accessToken`); use `--no-redact` only when
  necessary.
- Prefer `--config-dir setup/rest` in automation for deterministic discovery.

## References

- Full guide (project template): `skills/tools/testing/rest-api-testing/references/REST_API_TESTING_GUIDE.md`
- Report contract: `skills/tools/testing/rest-api-testing/references/REST_API_TEST_REPORT_CONTRACT.md`
- Report template: `skills/tools/testing/rest-api-testing/references/REST_API_TEST_REPORT_TEMPLATE.md`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/graysurf) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->