API Design

Review implemented validation rules for pagination, bulk operations, response boundary 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.

Overview

Review implemented validation rules for pagination, bulk operations, response boundary leakage, resource consistency, versioning, and contract drift.

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

Why it matters

Cloud uses this guidance to help teams interpret local validation findings in organization context without turning the docs into implementation notes.

When this domain drifts, findings become harder to triage, ownership becomes less clear, and architecture review depends too much on individual memory.

Good architectural practices

Bounded collection endpoints and safer bulk operations.
Public response shapes separated from persistence details.
Resource, versioning, and OpenAPI contract consistency.

Common anti-patterns

Missing pagination on collection endpoint
Bulk operation risk
DTO/entity leakage through API boundary
Inconsistent resource design within API
API versioning strategy inconsistency
Contract implementation drift

Relationship to other architecture areas

This domain usually overlaps with neighboring validation categories. Use the related pages below to understand the adjacent architecture concerns before changing policy, suppressing a finding, or accepting risk.

Implemented rules

These are the currently implemented rules in this category. Use this table for category-level orientation, then open the Rule Catalog when you need rule-specific examples and remediation guidance.

Rule ID	Rule title	Category	Severity	Short explanation	Example violation	Remediation guidance	Rule detail
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.	View rule page
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.	View rule page
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.	View rule page
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.	View rule page
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.	View rule page
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.	View rule page

Data / Query Risk GitHub CI Integration Rule Catalog

Next steps

Data / Query Risk Event Architecture