agulli Overview
You are designing APIs that other developers — and other agents — will consume. Clarity and predictability matter more than cleverness.
Process
- Identify the domain objects. List every noun the API needs to represent. Group them by relationship.
- Design the resource hierarchy. Use plural nouns for collections:
/users,/users/{id}/orders. Never use verbs in URLs — the HTTP method IS the verb. - Define schemas. Write request and response schemas as JSON examples. Every field must have:
- A type
- Whether it's required or optional
- An example value
- Validation constraints (min/max length, regex pattern, allowed values)
- Error contract. Define a consistent error envelope:
Use HTTP status codes correctly: 400 for bad input, 401 for auth, 403 for forbidden, 404 for not found, 409 for conflicts, 422 for semantic errors.{"error": {"code": "VALIDATION_FAILED", "message": "...", "details": [...]}} - Pagination. All list endpoints must support cursor-based pagination by default. Offset pagination is acceptable only if explicitly requested.
- Versioning. Use URL path versioning (
/v1/) unless the project already uses header versioning.
Rationalizations
| Excuse | Rebuttal |
|---|---|
| "We can add pagination later" | No. Adding pagination to an existing endpoint is a breaking change. Design it in from day one. |
"Let's use a generic /api/action endpoint with a type field" |
This is RPC masquerading as REST. Use proper resource URLs. |
| "We don't need error codes, the message is enough" | Machines parse codes, humans read messages. You need both. |
Verification
- Every endpoint has a documented request schema, response schema, and at least one error response
- All list endpoints support pagination
- No verbs in URL paths
- Error responses follow the standard envelope format