gh-levnikolaevich-claude-code-skills-full-development-workflow-skills/skills/ln-114-project-docs-creator/references/templates/api_spec_template.md

API Specification: {{PROJECT_NAME}}

Document Version: 1.0 Date: {{DATE}} Status: {{STATUS}} OpenAPI Version: 3.0.3

---

1. API Overview

1.1 Base URL

{{BASE_URL}}

1.2 API Design Principles

{{API_DESIGN_PRINCIPLES}}

1.3 API Versioning

{{API_VERSIONING}}

---

2. Authentication & Authorization

2.1 Authentication Methods

Supported Methods: {{AUTH_METHODS}}

JWT Token Format:

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "user_id",
    "role": "admin",
    "exp": 1234567890
  }
}

Token Expiration: {{TOKEN_EXPIRATION}}

2.2 Authorization (RBAC)

Roles: {{RBAC_ROLES}}

---

3. API Endpoints

3.1 Authentication Endpoints

Method	Endpoint	Description	Auth Required
POST	/auth/register	Register new user	No
POST	/auth/login	Login (email/password)	No
POST	/auth/refresh	Refresh access token	Yes (Refresh token)
POST	/auth/logout	Logout (invalidate tokens)	Yes
GET	/auth/me	Get current user info	Yes

Example: POST /auth/login

Request:

{
  "email": "user@example.com",
  "password": "secure_password"
}

Response (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "role": "editor"
  }
}

---

3.2 User Management Endpoints

Method	Endpoint	Description	Auth Required	Roles
GET	/users	List all users (paginated)	Yes	Admin
GET	/users/:id	Get user by ID	Yes	Admin, self
PUT	/users/:id	Update user	Yes	Admin, self
DELETE	/users/:id	Delete user	Yes	Admin
PATCH	/users/:id/password	Change password	Yes	Admin, self

Example: GET /users?page=1&limit=20

Response (200 OK):

{
  "data": [
    {
      "id": "uuid",
      "email": "user@example.com",
      "role": "editor",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

---

3.3 {{RESOURCE_1}} Endpoints

Method	Endpoint	Description	Auth Required
GET	/{{resource}}	List {{resource}}	Yes
GET	/{{resource}}/:id	Get {{resource}} by ID	Yes
POST	/{{resource}}	Create {{resource}}	Yes
PUT	/{{resource}}/:id	Update {{resource}}	Yes
DELETE	/{{resource}}/:id	Delete {{resource}}	Yes

---

3.4 {{RESOURCE_2}} Endpoints

{{RESOURCE_2_ENDPOINTS}}

---

4. Request & Response Formats

4.1 Common Query Parameters

Parameter	Type	Description	Example
page	integer	Page number (1-based)	?page=2
limit	integer	Items per page (max 100)	?limit=50
sort	string	Sort field (+asc, -desc)	?sort=-createdAt
filter	string	Filter expression	?filter=status:active
search	string	Search query	?search=keyword

4.2 Standard Response Structure

Success Response:

{
  "data": { /* resource data */ },
  "meta": { /* metadata, pagination */ }
}

Error Response:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": [ /* validation errors, if applicable */ ]
  }
}

---

5. Error Codes

5.1 HTTP Status Codes

Status	Meaning	When Used
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST
204	No Content	Successful DELETE
400	Bad Request	Invalid request format, validation errors
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Authenticated but insufficient permissions
404	Not Found	Resource not found
409	Conflict	Duplicate resource (email already exists)
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

5.2 Custom Error Codes

Code	HTTP Status	Description	Example
AUTH_INVALID_CREDENTIALS	401	Invalid email/password	Login failed
AUTH_TOKEN_EXPIRED	401	JWT token expired	Token needs refresh
AUTH_INSUFFICIENT_PERMISSIONS	403	User lacks required role	Admin-only action
VALIDATION_FAILED	422	Input validation failed	Missing required field
RESOURCE_NOT_FOUND	404	Requested resource not found	User ID not found
RESOURCE_CONFLICT	409	Resource already exists	Email already registered
RATE_LIMIT_EXCEEDED	429	Too many requests	100 req/min limit hit

Example Error Response:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed for request body",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      },
      {
        "field": "password",
        "message": "Password must be at least 8 characters"
      }
    ]
  }
}

---

6. Rate Limiting

Limits: {{RATE_LIMITS}}

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 75
X-RateLimit-Reset: 1640000000

---

7. Pagination

Request:

GET /users?page=2&limit=20

Response:

{
  "data": [ /* 20 users */ ],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": true
  },
  "links": {
    "self": "/users?page=2&limit=20",
    "first": "/users?page=1&limit=20",
    "prev": "/users?page=1&limit=20",
    "next": "/users?page=3&limit=20",
    "last": "/users?page=8&limit=20"
  }
}

---

8. OpenAPI Specification

OpenAPI Documentation: {{OPENAPI_LINK}}

Example OpenAPI Snippet (users endpoint):

paths:
  /users:
    get:
      summary: List all users
      tags: [Users]
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

---

9. Maintenance

Last Updated: {{DATE}}

Update Triggers:

• New API endpoints added
• Authentication/authorization changes
• Error code modifications
• Rate limiting adjustments
• API versioning (major/minor releases)

Verification:

• All endpoints documented with methods/paths/params/responses
• Authentication requirements specified for each endpoint
• Error codes match implementation
• OpenAPI specification up to date
• Rate limits tested and validated

---

Version: 1.0.0 Template Last Updated: 2025-11-16