AI & Agents
Skill
/api-design
RESTful API design best practices and conventions guide
Install
$ npx -y skills add leavesfly/jimi --skill api-design --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/api-design
Context preview
The summary Claude sees to decide when to auto-load this skill.
RESTful API design best practices and conventions guide
SKILL.md
api-design.SKILL.mdname: api-design description: RESTful API design best practices and conventions guide
API Design Skill
This skill provides comprehensive guidance for designing RESTful APIs following industry best practices.
Core Principles
1. Resource-Oriented Design
- Use nouns for resource names (e.g., `/users`, `/products`)
- Avoid verbs in URLs
- Use HTTP methods to represent actions
2. HTTP Methods
- **GET**: Retrieve resources
- **POST**: Create new resources
- **PUT**: Update entire resources
- **PATCH**: Partial updates
- **DELETE**: Remove resources
3. URL Structure
GET /api/v1/users - List all users
GET /api/v1/users/{id} - Get specific user
POST /api/v1/users - Create new user
PUT /api/v1/users/{id} - Update user
DELETE /api/v1/users/{id} - Delete user4. Response Format
- Use JSON as default format
- Use camelCase for field names
- Include metadata (pagination, timestamps)
5. Error Handling
{
"error": {
"code": "INVALID_REQUEST",
"message": "User ID must be a positive integer",
"details": []
}
}6. Status Codes
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 404: Not Found
- 500: Internal Server Error
Best Practices
- Version your APIs
- Use pagination for list endpoints
- Implement rate limiting
- Document with OpenAPI/Swagger