Inconsistent resource design within API

How to fix

1. Align route naming and response shape with adjacent resources.
2. Document intentional exceptions in the API style ADR.
3. Update clients and contracts together.

What it means

Related API endpoints appear to model resources inconsistently.

Why it matters

Consistent resource design improves client ergonomics and contract review.

Common causes

• Endpoints were added by different teams without a shared convention.
• A resource was renamed in code but not in the contract.
• Action-style routes mix with resource-style routes unnecessarily.

Example bad pattern

The API mixes /teams/:id/system, /systemTeams, and /assign-system for the same relationship.

Example good pattern

Relationship operations use one documented resource naming pattern.

Related files/config

• contracts/openapi.yaml
• apps/api/src

Related CLI commands

• archpilot validate
• archpilot validate --ci