1# API Contract Specialist Review Checklist

3Scope: When SCOPE_API=true

4Output: JSON objects, one finding per line. Schema:

5{"severity":"CRITICAL|INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"api-contract","summary":"...","fix":"...","fingerprint":"path:line:api-contract","specialist":"api-contract"}

6Optional: line, fix, fingerprint, evidence, test_stub.

7If no findings: output `NO FINDINGS` and nothing else.

8

9---

10

API Contract Specialist Review Checklist

Scope: When SCOPE_API=true Output: JSON objects, one finding per line. Schema: {"severity":"CRITICAL|INFORMATIONAL","confidence":N,"path":"file","line":N,"category":"api-contract","summary":"...","fix":"...","fingerprint":"path:line:api-contract","specialist":"api-contract"} Optional: line, fix, fingerprint, evidence, test_stub. If no findings: output NO FINDINGS and nothing else.

Raw lines 1 to 10

11## Categories

12

Categories

Raw lines 11 to 12

13### Breaking Changes

14- Removed fields from response bodies (clients may depend on them)

15- Changed field types (string → number, object → array)

16- New required parameters added to existing endpoints

17- Changed HTTP methods (GET → POST) or status codes (200 → 201)

18- Renamed endpoints without maintaining the old path as a redirect/alias

19- Changed authentication requirements (public → authenticated)

20

Breaking Changes

Removed fields from response bodies (clients may depend on them)
Changed field types (string → number, object → array)
New required parameters added to existing endpoints
Changed HTTP methods (GET → POST) or status codes (200 → 201)
Renamed endpoints without maintaining the old path as a redirect/alias
Changed authentication requirements (public → authenticated)

Raw lines 13 to 20

21### Versioning Strategy

22- Breaking changes made without a version bump (v1 → v2)

23- Multiple versioning strategies mixed in the same API (URL vs header vs query param)

24- Deprecated endpoints without a sunset timeline or migration guide

25- Version-specific logic scattered across controllers instead of centralized

26

Versioning Strategy

Breaking changes made without a version bump (v1 → v2)
Multiple versioning strategies mixed in the same API (URL vs header vs query param)
Deprecated endpoints without a sunset timeline or migration guide
Version-specific logic scattered across controllers instead of centralized

Raw lines 21 to 26

27### Error Response Consistency

28- New endpoints returning different error formats than existing ones

29- Error responses missing standard fields (error code, message, details)

30- HTTP status codes that don't match the error type (200 for errors, 500 for validation)

31- Error messages that leak internal implementation details (stack traces, SQL)

32

Error Response Consistency

New endpoints returning different error formats than existing ones
Error responses missing standard fields (error code, message, details)
HTTP status codes that don't match the error type (200 for errors, 500 for validation)
Error messages that leak internal implementation details (stack traces, SQL)

Raw lines 27 to 32

33### Rate Limiting & Pagination

34- New endpoints missing rate limiting when similar endpoints have it

35- Pagination changes (offset → cursor) without backwards compatibility

36- Changed page sizes or default limits without documentation

37- Missing total count or next-page indicators in paginated responses

38