Gateway Gus saysThe principle of least surprise: be consistent so developers can guess your API correctly.
A great API is predictable. Use consistent naming (plural nouns, snake_case or camelCase — pick one), consistent error shapes, consistent date formats (ISO 8601), and consistent pagination across every endpoint. When one endpoint behaves like the others, developers learn your API once and guess the rest right. Surprises cost integration time and trust.
Power-ups you unlock
Consistency makes an API guessable
Pick one casing/format and stick to it
Uniform errors, dates (ISO 8601), pagination
Predictability > cleverness
Timeout Titan attacks — common mistakes
Mixed casing/formats across endpoints
Different error shapes per route
Inconsistent date/time representations
Boss battleSpot three inconsistencies that would make an API surprising.
Example code
<!doctype html><html><head><meta charset="utf-8"></head>
<body style="background:#06040d;color:#e6e0ff;font-family:monospace;padding:20px"><pre>surprising: /users (camelCase) + /blog_posts (snake)
dates as epoch here, ISO there
consistent: one casing, one date format, one error shape</pre></body></html>