api-design-first

name	api-design-first
description	Design and document RESTful APIs using design-first principles with OpenAPI specifications. Use this skill when the user asks to design an API, create an API spec, plan endpoints, model request/response schemas, or discuss API versioning — even if they just say "design the API" or "create the OpenAPI spec". Not for cloudflare-worker-api.
version	0.2.10
category	platform
template_version	0.2
license	MIT

API Design First

Design RESTful APIs using design-first principles with comprehensive OpenAPI 3.0 specifications.

When to Use

• User asks to design an API or create an API spec
• Planning endpoints, modeling request/response schemas
• Discussing API versioning or OpenAPI/Swagger documentation
• Even if they just say "design the API" or "create the OpenAPI spec"

Design Principles

1. API-First Mindset

• Design the API contract before implementation
• Use OpenAPI 3.0 as the source of truth
• Generate code from specifications, not vice versa

2. RESTful Design

• Use nouns for resources (not verbs)
• Leverage HTTP methods semantically
• Implement proper status codes
• Support filtering, pagination, and sorting

3. Consistency

• Follow naming conventions throughout
• Use consistent request/response formats
• Maintain backward compatibility with versioning

Resource Naming

GET    /users              # List users
GET    /users/{id}         # Get specific user
POST   /users              # Create user
PUT    /users/{id}         # Update user (full)
PATCH  /users/{id}         # Partial update
DELETE /users/{id}         # Delete user
GET    /users/{id}/orders  # Sub-resource collection

HTTP Status Codes

Code	Usage
200	Successful GET, PUT, PATCH
201	Successful POST (resource created)
204	Successful DELETE
400	Bad request (validation error)
401	Unauthorized
403	Forbidden
404	Resource not found
409	Conflict (duplicate, etc.)
422	Unprocessable entity
429	Rate limited
500	Server error

Request/Response Patterns

Pagination

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=8"
  }
}

Error Response

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

OpenAPI Structure

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success

Versioning Strategies

1. URL Path: /v1/users, /v2/users
2. Header: Accept: application/vnd.api+json;version=2
3. Query Param: /users?api-version=2

See Also

• cloudflare-worker-api — Cloudflare Worker API routes
• secure-invite-and-access — Auth endpoints and permissions

Rationalizations

Rationalization	Reality
"We'll design the API after implementing the feature."	Post-hoc API design leads to inconsistent contracts, breaking changes, and poor developer experience.
"Verbs in URLs are fine — /getUser is clear."	REST uses HTTP methods for actions; verb-based URLs break caching, proxying, and violate RESTful conventions.

Red Flags

• Designing endpoints without an OpenAPI specification first
• Using verbs in resource URLs instead of nouns with HTTP methods
• Ignoring versioning strategy until breaking changes force a rewrite

References

• references/rest-guidelines.md - Comprehensive REST design guidelines
• references/openapi-examples.md - Complete OpenAPI 3.0 specification examples
• references/naming-conventions.md - Resource and field naming standards

Voice & Context

• Default: professional + blog
• Reference: voice-profiles skill for definitions and auto-detection.