hummbl-io/agent-skills/api-design
Claude Code and agent skill by hummbl-io/agent-skills
Trust tier 3
- community
Source check pending
Checking that the SKILL.md file is still in the repository.
Design REST/HTTP APIs with consistent patterns -- endpoints, errors, pagination, auth.
Install
npx vskill@latest install hummbl-io/agent-skills/api-designSKILL.md
The same SKILL.md was published earlier as hummbl-io/agent-skills/api-design.
API Design
Design consistent HTTP APIs following REST conventions and our project patterns.
Execution
1. Define resources
What are the nouns? Map them to endpoints:
2. Apply conventions
| Convention | Pattern | |
|---|---|---|
| Versioning | /api/v1/ prefix | |
| Naming | Plural nouns, kebab-case ([bus-messages], not [busMessages]) | |
| Filtering | Query params: ?type=STATUS&since=2026-03-16 | |
| Pagination | ?limit=20&offset=0, return total in response | |
| Sorting | ?sort=-created_at (prefix - for descending) | |
| Errors | {"error": {"code": "NOT_FOUND", "message": "Agent not found"}} | |
| Auth | Bearer token in Authorization header | |
| Content-Type | application/json always |
3. Define error codes
| HTTP Status | When | Error Code | |
|---|---|---|---|
| 400 | Bad request body/params | VALIDATION_ERROR | |
| 401 | Missing/invalid auth | UNAUTHORIZED | |
| 403 | Authenticated but not allowed | FORBIDDEN | |
| 404 | Resource not found | NOT_FOUND | |
| 409 | Conflict (e.g., duplicate) | CONFLICT | |
| 422 | Valid JSON but invalid semantics | UNPROCESSABLE | |
| 429 | Rate limited | RATE_LIMITED | |
| 500 | Internal error | INTERNAL_ERROR |
4. Design for our stack
- Stdlib only: use
http.serveror document as FastAPI (dashboard only) - JSON schemas from
contracts/are the source of truth - IDP delegation tokens for auth where applicable
- Circuit breaker wrapping for external calls
5. Write OpenAPI stub (optional)
Output Format
Base120 Context
- Primary: CO9 (Interface Contracts)
- Related: SY12 (Protocol Standards), CO8 (Layered Abstraction)
Security
- Security scanPassed, 90 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/api-design/SKILL.md
Popularity
- 7-day trend score
- 5
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/hummbl-io/agent-skills/api-design)