API Design That Developers Actually Love — RESTful Done Right

The Problem

Bad API design is permanent. Once clients integrate with your API, changing it breaks them. The most common API design mistakes:

• Inconsistent naming (/getUsers vs /users vs /user/list)
• No pagination (return 50,000 records in one response)
• No versioning (break everyone on every update)
• Generic error messages ({"error": "something went wrong"})
• No rate limiting (one bad actor takes down your API)
• Authentication as an afterthought
• No HATEOAS or discoverability
• Inconsistent response formats across endpoints

Most teams design APIs endpoint-by-endpoint as they build features. No upfront design. No consistency guidelines. No schema. The result is an API that looks like it was designed by 7 different people (because it was).

The Solution

The API Design skill generates complete, consistent API specifications from a description of your domain and resources. OpenAPI 3.1 spec, authentication design, pagination, filtering, error handling — all consistent from day one.

The Process

You: Design a RESTful API for a project management tool:
Resources: projects, tasks, users, comments, labels
Features: task assignment, due dates, priority levels,
file attachments, activity feed
Auth: JWT with refresh tokens
Need: OpenAPI spec, pagination, filtering, error handling

The agent generates a complete OpenAPI 3.1 specification with consistent patterns across all resources — proper HTTP methods, status codes, pagination (cursor-based), filtering, sorting, error response format, authentication flow, rate limit headers, and HATEOAS links.

Every endpoint follows the same conventions:

• GET /v1/projects — list with pagination, filtering, sorting
• POST /v1/projects — create with validation
• GET /v1/projects/{id} — get single with field selection
• PATCH /v1/projects/{id} — partial update (not PUT)
• DELETE /v1/projects/{id} — soft delete with 204
• GET /v1/projects/{id}/tasks — nested resources

Error format is consistent everywhere:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Task title is required",
    "details": [
      { "field": "title", "reason": "required", "message": "Title cannot be empty" }
    ],
    "requestId": "req_abc123",
    "documentation": "https://api.myapp.com/docs/errors#VALIDATION_ERROR"
  }
}

The Results

Setup on MrChief

skills:
  - api-design
  - technical-writing  # For API documentation