API Design

Review implemented validation rules for pagination, bulk operations, DTO/entity leakage, resource consistency, versioning, and contract drift.

Why it matters

API Design findings keep public API behavior bounded, contract-aligned, and easier for clients to use safely.

What this category covers

Bounded collection endpoints and safer bulk operations.
Public DTOs separated from persistence entities.
Resource, versioning, and OpenAPI contract consistency.

Implemented rules

These are the currently implemented rules in this category. Cloud stores and displays the uploaded findings from local validation; it does not add future or speculative rules.

Rule ID	Rule title	Category	Severity	Short explanation	Example violation	Remediation guidance
AP-API-010	Missing pagination on collection endpoint	API Design	warning	Flags collection endpoints that do not expose clear pagination or bounded result controls.	GET /repositories returns every repository in the organization with no limit parameter.	Add limit/cursor or page parameters. Document defaults and maximum page size in the API contract. Return pagination metadata when clients need it.
AP-API-011	Bulk operation risk	API Design	warning	Flags bulk API operations that lack clear safeguards.	POST /repositories/delete accepts an arbitrary list of ids with no max size or audit context.	Add request size limits and validation. Require explicit authorization for bulk actions. Document idempotency, failure behavior, and audit expectations.
AP-API-012	DTO/entity leakage through API boundary	API Design	warning	Flags APIs that expose persistence entities or internal DTOs across the external boundary.	A route returns the full Prisma User record including internal flags.	Introduce explicit public request/response DTOs. Map only intended fields across the API boundary. Regenerate or update the API contract after the change.
AP-API-013	Inconsistent resource design within API	API Design	warning	Flags REST resources that use inconsistent naming, shape, or operation patterns.	The API mixes /teams/:id/system, /systemTeams, and /assign-system for the same relationship.	Align route naming and response shape with adjacent resources. Document intentional exceptions in the API style ADR. Update clients and contracts together.
AP-API-014	API versioning strategy inconsistency	API Design	warning	Flags API routes or contracts that do not follow the repository's versioning strategy.	Most routes use /api/v1, but a new public endpoint is exposed under /api/reports.	Move the route under the expected versioned path. Update OpenAPI paths to match implementation. Document any intentionally unversioned internal endpoint.
AP-API-015	Contract implementation drift	API Design	warning	Flags API behavior whose implementation and contract appear to have drifted apart.	OpenAPI says PATCH /repositories/:id accepts status, but implementation expects lifecycleStatus.	Regenerate or update the API contract. Align implementation with the documented contract where the contract is correct. Review contract changes in the same pull request as API changes.

Data / Query Risk GitHub CI Integration Rule Catalog

Next steps

Data / Query Risk Event Architecture