Back to learn
Backend6 min
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. Use JSON bodies for structured POST requests and query parameters only for simple bounded reads.
02
Make errors script-friendly
Return stable status codes and a message that can be printed directly in CI. Reserve 400 for malformed requests and 422 for valid requests with invalid content.
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.