API ergonomics for small utilities
Request shapes, error status codes, and limits that make automation endpoints useful from scripts and CI.
Takeaway
Small utility APIs should be boring: explicit inputs, predictable limits, JSON responses, and clear failure messages.
01
Keep request shapes small
Accept the minimum fields needed for the operation. Small request shapes are easier to call from curl, CI, and internal scripts because the user can understand the contract without reading a client SDK.
Use JSON bodies for structured POST requests and query parameters only for simple bounded reads. That split keeps formatter, converter, and inspector endpoints consistent.
- Name inputs plainly, such as input, mode, algorithm, count, and timeZone.
- Reject unknown modes with a readable 422 response.
- Keep defaults documented beside examples rather than hiding them in implementation details.
02
Make errors script-friendly
Return stable status codes and a message that can be printed directly in CI. Script users should not need to scrape HTML, parse stack traces, or guess whether an error is retryable.
Reserve 400 for malformed requests, 413 for payloads that exceed limits, and 422 for valid requests with invalid content. This gives automation enough structure to fail loudly and correctly.
- Return a top-level ok field and a human-readable message.
- Keep validation errors deterministic so tests can assert them.
- Avoid logging raw inputs while still logging route, status, and error category.
03
Document limits beside examples
Put size, count, and verification limits next to curl examples. Users should not need to discover operational boundaries by failing in automation.
- Publish count clamps for UUID and password generation.
- Name request size limits for hash, YAML, XML, text, token, and date endpoints.
- State when an endpoint decodes or inspects data without verifying trust.
request shape
json
{
"input": "{\"ok\": true}",
"mode": "format"
}