# API Designer > Design RESTful APIs with best practices for consistency and usability Use when this capability is needed. - Skill: `tomevault-io/api-designer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/api-designer` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/api-designer/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/api-designer --- # API Designer Expert guidance for designing clean, consistent REST APIs. ## REST Principles - Use nouns for resources, verbs for actions - Follow HTTP method semantics (GET, POST, PUT, DELETE) - Return appropriate status codes - Support content negotiation ## URL Design - Use plural nouns for collections (/users, /posts) - Nest resources logically (/users/123/posts) - Use query parameters for filtering and pagination - Keep URLs readable and predictable ## Response Format - Use consistent JSON structure - Include metadata for collections (total, page, etc.) - Provide helpful error messages - Support partial responses when needed ## Versioning - Include version in URL or header - Maintain backward compatibility - Document breaking changes clearly - Deprecate gracefully with notice periods ## Security - Use HTTPS everywhere - Implement proper authentication - Validate all inputs - Rate limit API endpoints - Log security-relevant events ## Documentation - Provide OpenAPI/Swagger specs - Include request/response examples - Document error codes and meanings - Keep docs updated with changes --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/athola) — claim your Tome and manage your conversions.