---
name: api-verify
description: Verify GCC Player API changes before committing — drive every endpoint over HTTP with a real key, prove the auth and entitlement gates still bite, read the error log on a 500, and clean up scratch files. Use before every commit touching app/api.
---

# Verifying Player API changes

Reading the code is not verification. Drive the real endpoint over HTTP.

## 1. Get a key

```bash
docker compose -f dev/docker-compose.yml --env-file dev/.env exec -T db \
  sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" gcc -N -e \
  "SELECT id, nic, api_key FROM user WHERE api_key IS NOT NULL AND api_key <> \"\" LIMIT 3;"'
```

## 2. Every endpoint still routes

The fastest regression check after any refactor — a rename or a moved allowlist
shows up here immediately:

```bash
KEY=gccapi_...
for a in meta.endpoints meta.whoami ranks.top50 dsr.battles \
         planets.types races.list ships.list; do
  printf "%-16s %s\n" "$a" \
    "$(curl -s -o /dev/null -w '%{http_code}' -H "X-API-Key: $KEY" \
       "http://127.0.0.1:8888/api/?action=$a")"
done
```

All 200. A **500** on one action while others pass usually means the registry and
`this.routable` disagree.

## 3. Auth still bites

```bash
curl -s -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:8888/api/?action=meta.endpoints"
# 401 — never 200
```

## 4. Discovery matches reality

```bash
curl -s -H "X-API-Key: $KEY" "http://127.0.0.1:8888/api/?action=meta.endpoints"
```

A new endpoint missing here is missing from `Registry.cfc`. Check `meta.whoami`
too: `available` must not list anything the caller would actually be 403'd on.

## 5. Gated endpoints, from the denied side

If the change touches an access rule, test the account that should **fail** —
see the `api-access-rule` skill. A gate proven only from the allowed side is not
proven.

## 6. On a 500, read the log

The response body is deliberately opaque. The real message, with
`template:line`, is here:

```bash
docker compose -f dev/docker-compose.yml --env-file dev/.env exec -T app \
  sh -c 'tail -20 /opt/lucee/server/lucee-server/context/logs/gcc_player_api.log'
```

## 7. Cache is not hiding your change

Cached responses live in application scope. If a change is not showing up:

```cfml
<cfscript>applicationStop();</cfscript>
```

Check `meta.cached` and `cache_age_secs` in the response before concluding the
code is wrong.

## 8. Clean up

```bash
git status --short app/api
```

- No scratch `.cfm` harnesses anywhere under `app/`.
- Any test rows written to `gcc_log.api_log` during testing removed if they
  would confuse later analysis.
- `test.cfm` still present is fine on dev — but it **must not reach
  production**.