dileepkpandiya API Design Skill
Use this skill when designing HTTP APIs, SDK methods, command interfaces, or internal service contracts. Optimize for predictable behavior, explicit errors, and long-term compatibility.
Design checklist
Define the primary user journey before naming endpoints or methods. Choose resource names that describe domain concepts rather than implementation details. Use consistent pagination, filtering, sorting, and idempotency conventions across the API. Treat versioning as a compatibility strategy, not as a substitute for careful change management.
Request and response guidance
Prefer structured request bodies for operations with multiple parameters. Return stable identifiers and timestamps in machine-readable formats. Include error codes that clients can branch on, plus messages that humans can understand. Make partial failure behavior explicit for batch operations.
Evaluation guidance
Call out ambiguous ownership of resources, overloaded parameters, and hidden side effects. Recommend defaults that reduce client surprise. Explain tradeoffs when there are multiple acceptable designs. When suggesting examples, keep payloads small but realistic enough to validate the contract.