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

HTTP Methods

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)

Client Error (4xx)

Server Error (5xx)

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