api-design

API Design Skill

Skill Metadata

• Name: api-design
• Description: Design RESTful APIs with consistent conventions across all services
• User Invocable: Yes (via /api-design)

---

Overview

This skill guides the design of RESTful APIs for any backend service, ensuring consistency, security, and usability across all endpoints. The discipline is stack-agnostic: the examples below use TypeScript and Zod for concreteness, but the conventions apply equally to Python, Go, Java, or any other language.

---

API Design Principles

1. Resource-Based URLs

Good
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
DELETE /api/v1/users/:id

Avoid
GET    /api/v1/getUsers
POST   /api/v1/createUser
POST   /api/v1/deleteUser

2. Consistent Response Format

{
  "success": true,
  "data": {
    // Resource data
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [
      { "field": "email", "message": "Email is required" }
    ]
  }
}

3. HTTP Status Codes

Code	Meaning	Use Case
200	OK	Successful GET, PUT
201	Created	Successful POST (created resource)
204	No Content	Successful DELETE
400	Bad Request	Validation error
401	Unauthorized	Missing/invalid auth
403	Forbidden	Lacks permission
404	Not Found	Resource not found
409	Conflict	Duplicate resource
422	Unprocessable	Business rule violation
500	Internal Error	Server error

4. Versioning

/api/v1/users
/api/v2/users

Embed the version in the URL path. Never negotiate it via a header unless a downstream client framework forces you to.

5. Filtering, Sorting, Pagination

GET /api/v1/users?status=active&sort=-createdAt&page=1&limit=20

# Filter operators
?status=active           # Equality
?amount_gte=100         # Greater than or equal
?amount_lte=1000        # Less than or equal
?name_like=john         # Contains

# Sorting
?sort=name              # Ascending
?sort=-createdAt        # Descending (prefix with -)
?sort=status,-createdAt # Multiple fields

# Pagination
?page=1&limit=20        # Page-based
?cursor=abc123&limit=20 # Cursor-based