Best for
- APIs grown by many hands into many dialects
- A consistency pass before going public or signing an integration
- Writing the house conventions by extracting them from your best endpoints
What you give it
- Your API surface: spec, docs, or the route code itself
What you get back
- An inconsistency report: every place the API disagrees with itself, grouped by kind
- A proposed house convention per topic — derived from your own dominant patterns
- The fix list split into compatible-now and needs-versioning
How it works
- Sweeps the whole surface and catalogues each convention topic: naming, verbs, status codes, errors, pagination, filtering, time, ids, nulls.
- Derives the house rule from your dominant existing pattern where it is sound — minimising the change surface.
- Separates fixes by compatibility: what can align today versus what must wait for a version boundary.
- Writes the conventions down as the living document new endpoints get reviewed against.
Example
You: Review our 60-endpoint API before the partner integration starts.
Result: The report: three naming styles (camel, snake, and one endpoint in both), four error shapes, dates in two formats plus one epoch, pagination by offset here and cursor there, and a DELETE that returns 200 with a body saying 'error'. House conventions proposed from your own majority patterns; 31 fixes applicable compatibly now, 9 queued behind the next version boundary — partner integration started against the written conventions.
Limits — please read
- Taste wars (camel vs snake) are settled by your majority pattern, not ideology — it says which and why.
- Already-public inconsistencies may be cheaper to document than to fix; the report prices both paths.
- It reviews shape and semantics; deep behaviour testing is a different pass.