REST API Design Skill

Expert assistance for designing RESTful APIs following best practices.

Capabilities

• •Design resource-oriented APIs
• •Implement proper HTTP methods and status codes
• •Configure API versioning strategies
• •Implement pagination patterns
• •Design error responses
• •Apply HATEOAS principles

Usage

Invoke this skill when you need to:

• •Design new REST APIs
• •Review existing API design
• •Implement pagination
• •Define error handling
• •Version APIs

Design Principles

Resource Naming

# Good - nouns, plural
GET /api/users
GET /api/users/123
GET /api/users/123/posts

# Bad - verbs, actions in URL
GET /api/getUsers
GET /api/users/123/getPosts
POST /api/createUser

HTTP Methods

Pagination Response

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2",
    "prev": null
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

Best Practices

• •Use proper HTTP status codes
• •Implement consistent error responses
• •Version APIs from the start
• •Document with OpenAPI

Target Processes

• •api-design
• •backend-development
• •microservices-architecture