api-designlisted
Install: claude install-skill parisgroup-ai/imersao-ia-setup
# API Design Skill
This skill ensures every API is consistent, well-documented, and follows industry best practices.
## URL Structure
```
/api/v1/{resource} # Collection
/api/v1/{resource}/{id} # Single item
/api/v1/{resource}/{id}/{sub-resource} # Nested resource
```
**Rules:**
- Use plural nouns: `/users`, `/orders`, `/products`
- Use kebab-case for multi-word: `/order-items`
- Max 2 levels of nesting
## HTTP Methods
| Method | Purpose | Idempotent | Safe |
|--------|---------|------------|------|
| GET | Retrieve | Yes | Yes |
| POST | Create | No | No |
| PUT | Replace | Yes | No |
| PATCH | Update | Yes | No |
| DELETE | Remove | Yes | No |
## Response Format
### Success
```json
{
"data": { },
"meta": {
"requestId": "req_xyz789",
"timestamp": "2024-01-15T10:30:00Z"
}
}
```
### Error
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{ "field": "email", "message": "Must be valid email" }
]
},
"meta": { "requestId": "req_xyz789" }
}
```
## Status Codes
| Code | When to Use |
|------|-------------|
| 200 | Successful GET, PUT, PATCH |
| 201 | Successful POST (created) |
| 204 | Successful DELETE |
| 400 | Bad request |
| 401 | Not authenticated |
| 403 | Not authorized |
| 404 | Not found |
| 409 | Conflict |
| 422 | Validation failed |
| 429 | Rate limited |
| 500 | Server error |
## Pagination
```json
{
"data": [...],
"pagination": {