agent-ops-api-review

name	agent-ops-api-review
description	Platform/Language agnostic API delivery and correctness auditor. Use when project contains API endpoints to verify contract alignment, endpoint behavior, and test coverage.
category	analysis
invokes	["agent-ops-state","agent-ops-tasks"]
invoked_by	["agent-ops-critical-review","agent-ops-validation"]
state_files	{"read":["constitution.md","baseline.md","focus.md","issues/*.md"],"write":["focus.md","issues/*.md"]}

Skill: agent-ops-api-review

Platform/Language agnostic API delivery and correctness auditor

---

Purpose

Perform a critical, thorough, evidence-based audit of an API implementation and its endpoints. Verify that the API:

• Produces the expected outcomes
• Behaves correctly across success and failure paths
• Matches its OpenAPI/Swagger contract
• Has adequate tests to prove required behavior

No credit without evidence. Spec is not proof. Tests are not proof unless they assert required outcomes.

---

Triggers

• Project contains API endpoints (REST, GraphQL, gRPC)
• OpenAPI/Swagger spec exists
• User requests API review
• agent-ops-critical-review detects API patterns

---

Inputs

You will be given some or all of:

• Repository / codebase / diff
• OpenAPI/Swagger spec (file or generated)
• Unit test suite
• Optional: CI logs, runtime logs, sample requests/responses

If the OpenAPI spec is not available, identify where it should exist and treat missing spec as a finding.

---

Non-Negotiable Rules

• No credit without evidence
• Spec is not proof — implementation must match it
• Tests are not proof unless they assert required outcomes and would fail on regression
• Every claim must cite concrete locations (files/endpoints/tests/spec paths)

---

Mandatory Audit Outputs

1. Endpoint Inventory

List all endpoints, grouped by resource/domain:

• Method + route + auth requirement
• Request/response shape references (OpenAPI path refs if available)

2. Contract Alignment Matrix

For each endpoint:

Endpoint	Spec Ref	Impl Ref	Tests Ref	Status
GET /users	paths./users.get	user_router.py:45	test_users.py:12	aligned
POST /users	paths./users.post	user_router.py:78	—	untested

Status values: aligned | partially_aligned | misaligned | unverifiable

3. Findings

Each finding must include:

• Severity: must_fix | strongly_recommended | discuss
• Category: Which audit axis (A1-A10)
• Endpoint(s) affected
• File references
• Evidence
• Actionable recommendation

4. Test Gap Assessment

• What is proven by unit tests
• What cannot be proven without integration tests
• Minimum required integration tests to establish confidence

5. Verdict

• PASS: No must_fix and no misaligned endpoints
• FAIL: Any must_fix or misaligned endpoint

---

Mandatory Audit Axes

Explicitly evaluate each axis. If not applicable, say why.

A1: OpenAPI Contract Correctness & Drift

• Does the OpenAPI spec reflect actual API behavior?
• Are operationIds stable and meaningful?
• Are schemas precise (required fields, formats, nullability)?
• Are error responses specified and accurate?
• Are examples present and representative?

Flag: spec drift, underspecified schemas, missing error models

A2: Endpoint Behavior & Outcome Verification

For each endpoint:

• Does it produce the expected domain outcome, not just a response?
• Are side effects correct (create/update/delete/idempotency)?
• Are status codes correct and consistent?
• Are edge cases handled (empty, invalid, not found, conflict)?

Flag: wrong status codes, incorrect behavior, missing edge cases

A3: Request Validation & Error Semantics

• Is input validation explicit and consistent?
• Are validation errors structured and stable (machine-readable)?
• Are error codes/messages consistent across endpoints?
• Clear distinction between 4xx (client) vs 5xx (server) vs 409 (conflict)?
• Are errors ever swallowed or turned into "200 with error payload"?

Flag: inconsistent error shapes, silent failures, leaking internal details

A4: Authentication, Authorization, and Tenant Boundaries

• Are endpoints protected appropriately?
• Are authorization rules enforced server-side?
• Are tenant boundaries enforced (if multi-tenant)?
• Is identity propagated and validated correctly?

Flag: auth bypass risk, missing authorization checks, privilege escalation

A5: Pagination, Filtering, Sorting, and Field Selection (HIGH SCRUTINY)

Field Selection / Sparse Fieldsets

• Is it specified in OpenAPI?
• Does implementation whitelist fields (no arbitrary property exposure)?
• Are invalid field selections rejected with clear errors?

Filtering & Sorting

• Are filters validated and whitelisted?
• Is filter syntax consistent?
• Are unknown filters rejected (not ignored)?

Pagination

• Cursor vs offset semantics clear?
• Limits enforced?
• Deterministic ordering guaranteed?

Flag: field selection leaking sensitive data, injection risks, unstable paging

A6: Idempotency, Concurrency, and Caching

• Are PUT/PATCH/POST idempotency rules clear and honored?
• Are idempotency keys supported where required?
• Are concurrency controls present (ETag/If-Match) if needed?
• Are cache headers correct?

Flag: duplicate side effects on retries, lost updates

A7: Resource Modeling & API Evolution

• Consistent resource naming and hierarchy?
• Versioning strategy (URL/header/content negotiation)?
• Backward compatibility expectations?
• Deprecation policy?

Flag: breaking changes without version bump, inconsistent modeling

A8: Content Negotiation, Media Types, and Serialization

• Are content types explicit and correct?
• Are nullability and optional fields stable?
• Are time/date formats consistent and documented?
• Are enums stable?

Flag: ambiguous serialization, inconsistent date formats

A9: Observability, Correlation, and Operability

• Request IDs / correlation IDs present?
• Structured logging around failures?
• Metrics around key endpoints?
• Rate limiting (if required)?
• Are sensitive values excluded from logs?

Flag: inability to debug production issues, sensitive leakage

A10: Testing Strategy (Unit vs Integration vs Contract)

Unit tests prove:

• Handler logic (pure outcomes)
• Validation logic
• Error mapping

Integration tests required when:

• Behavior depends on routing/middleware/auth pipeline
• Serialization/deserialization matters
• DB/transaction boundaries matter
• OpenAPI contract needs proof

Contract tests required when:

• Clients depend on OpenAPI schema stability
• Multiple services integrate

Flag: tests only assert status codes, mocking away critical pipeline behavior

---

Severity Rules

must_fix

• Misaligned OpenAPI vs implementation for public endpoints
• Incorrect status codes or error semantics
• Auth/tenant boundary weakness
• Field selection/filtering security risks
• Untested critical behavior

strongly_recommended

• Partial contract coverage
• Missing integration tests for pipeline-dependent behavior
• Inconsistent patterns causing client breakage risk

discuss

• Spec ambiguity
• Alternative evolution strategies

---

Output Format

# API Audit Report

## Scope
What was reviewed (repo/diff/spec/tests).

## Endpoint Inventory
### Resource: Users
- GET /users (paths./users.get → user_router.py:45)
- POST /users (paths./users.post → user_router.py:78)

## Contract Alignment Matrix
| Endpoint | Spec Ref | Impl Ref | Tests Ref | Status |
|----------|----------|----------|-----------|--------|

## Findings

### Must Fix
- **[F001] Missing auth check on DELETE /users/{id}**
  - Endpoint: DELETE /users/{id}
  - Evidence: user_router.py:120 has no @require_auth decorator
  - Impact: Any user can delete any other user
  - Recommendation: Add authorization check

### Strongly Recommended
...

### Discuss
...

## Test Gap Assessment
- **Proven by unit tests**: Validation logic, error mapping
- **Requires integration tests**: Auth pipeline, OpenAPI contract
- **Minimum integration test set**: [list]

## Verdict
PASS | FAIL

---

Forbidden Behaviors

• ❌ Generic "best practices" lists
• ❌ Speculative scalability advice
• ❌ "Looks fine" without evidence
• ❌ Accepting OpenAPI or tests as proof without alignment verification

---

End Condition

Every endpoint accounted for with:

• Spec alignment status
• Implementation evidence
• Test evidence
• Explicit gaps and required tests