Api Design

API Design Skill

Purpose

Standards and best practices for designing RESTful APIs.

Auto-Invoke Triggers

• Designing new API endpoints
• Creating OpenAPI documentation
• Implementing API versioning
• Designing error responses
• Implementing pagination

---

REST API Principles

Resource Naming

• Use nouns, not verbs: /users not /getUsers
• Use plural nouns: /users not /user
• Use kebab-case: /user-profiles not /userProfiles
• Use lowercase only
• Max 2 levels nesting: /users/{id}/posts

URL Patterns

| Pattern | Example | Use Case | |---------|---------|----------| | Collection | /users | List resources | | Item | /users/{id} | Single resource | | Nested | /users/{id}/posts | Related resources | | Action | /users/{id}/activate | Non-CRUD operations |

---

HTTP Methods

| Method | Purpose | Idempotent | Safe | Has Body | |--------|---------|------------|------|----------| | GET | Read | Yes | Yes | No | | POST | Create | No | No | Yes | | PUT | Replace entire resource | Yes | No | Yes | | PATCH | Partial update | No | No | Yes | | DELETE | Remove | Yes | No | No |

Method Selection Rules

• GET for retrieval only, never modify state
• POST for creation, returns 201 with Location header
• PUT replaces entire resource, all fields required
• PATCH for partial updates, only changed fields
• DELETE returns 204 No Content on success

---

Status Codes

Success (2xx)

| Code | Use Case | |------|----------| | 200 OK | GET, PUT, PATCH success | | 201 Created | POST success (+ Location header) | | 204 No Content | DELETE success |

Client Error (4xx)

| Code | Use Case | |------|----------| | 400 Bad Request | Malformed request, validation error | | 401 Unauthorized | Authentication required | | 403 Forbidden | Authenticated but no permission | | 404 Not Found | Resource doesn't exist | | 409 Conflict | Resource state conflict | | 422 Unprocessable Entity | Semantic validation error | | 429 Too Many Requests | Rate limit exceeded |

Server Error (5xx)

| Code | Use Case | |------|----------| | 500 Internal Server Error | Unexpected error | | 502 Bad Gateway | External service failure | | 503 Service Unavailable | Temporarily down |

---

Response Format Standards

Success Response Structure

• Single resource: { "data": { ... } }
• Collection: { "data": [...], "pagination": {...} }
• Include only requested/necessary fields

Error Response Structure

Required fields:

• code - Machine-readable error code
• message - Human-readable description

Optional fields:

• details - Field-specific errors (validation)
• correlationId - For debugging/support

Pagination Standards

• Default page size: 20
• Maximum page size: 100
• Use cursor-based for large datasets
• Use offset-based for simple cases
• Always include: page, pageSize, totalItems, totalPages

---

Query Parameters

Filtering

• Simple: ?status=active
• Multiple: ?status=active&role=admin
• Range: ?createdAt[gte]=2024-01-01
• Search: ?search=keyword

Sorting

• Ascending: ?sort=createdAt
• Descending: ?sort=-createdAt
• Multiple: ?sort=lastName,firstName

Field Selection

• Sparse fields: ?fields=id,email,username
• Reduces payload size

---

Versioning Strategy

Recommended: URL Path Versioning

• Format: /api/v1/resource
• Clear, cacheable, easy to implement
• Support minimum N-1 versions

Deprecation Rules

• Announce 6 months before removal
• Include Sunset header on deprecated versions
• Document migration path

---

Security Requirements

Authentication

• Use Bearer tokens (JWT) for user auth
• Use API keys for service-to-service
• Never pass credentials in URL

Authorization

• Check permissions on every request
• Validate resource ownership
• Use principle of least privilege

Rate Limiting

• Implement per-user and per-endpoint limits
• Return rate limit headers
• Return 429 with Retry-After

---

Documentation Requirements

OpenAPI/Swagger Must Include

• All endpoints with methods
• Request/response schemas
• Parameter descriptions
• Error responses
• Authentication methods
• Examples for each endpoint

---

API Design Checklist

Naming

• [ ] URLs use plural nouns
• [ ] URLs use kebab-case
• [ ] No verbs in URLs (except actions)
• [ ] Consistent naming across endpoints

HTTP Semantics

• [ ] Correct method for each operation
• [ ] Appropriate status codes
• [ ] 201 + Location header for POST
• [ ] 204 for successful DELETE

Data

• [ ] Consistent response envelope
• [ ] Clear validation error messages
• [ ] Pagination for collections
• [ ] Field selection supported

Security

• [ ] Authentication required where needed
• [ ] Authorization on resources
• [ ] Rate limiting implemented
• [ ] Input validation complete

Documentation

• [ ] OpenAPI spec complete
• [ ] Examples provided
• [ ] Errors documented
• [ ] Versioning documented

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: komluk
• Source: komluk/scaffolding
• License: MIT

Install and usage instructions live in the source repository linked above.