API Design Validator

Purpose & When-To-Use

Trigger conditions:

• Designing new REST or GraphQL API endpoints
• Validating existing API against security best practices
• Generating OpenAPI 3.x or GraphQL schema documentation
• API security audit or OWASP API Security Top 10 compliance check
• Designing backwards-compatible API versioning strategy
• Standardizing pagination, filtering, or error handling patterns
• Pre-deployment API quality gate

Not for:

• API performance load testing (use specialized tools)
• Real-time API monitoring (use APM solutions)
• API gateway configuration (infrastructure-specific)
• Client SDK generation (use code generation tools)

Pre-Checks

Time normalization:

• Compute NOW_ET using NIST/time.gov semantics (America/New_York, ISO-8601): 2025-10-25T21:30:36-04:00
• Use NOW_ET for all citation access dates

Input validation:

• api_type must be exactly "REST" or "GraphQL"
• api_spec if provided must be valid JSON/YAML for REST or SDL string for GraphQL
• validation_tier must be: T1 or T2
• security_requirements if provided must be valid object with boolean flags
• versioning_strategy must be one of: none, path, header, query (for REST only)

Source freshness:

• OpenAPI 3.1.0 Specification (accessed 2025-10-25T21:30:36-04:00): https://spec.openapis.org/oas/v3.1.0
• GraphQL Specification (accessed 2025-10-25T21:30:36-04:00): https://spec.graphql.org/October2021/
• OWASP API Security Top 10 2023 (accessed 2025-10-25T21:30:36-04:00): https://owasp.org/API-Security/editions/2023/en/0x11-t10/
• HTTP Semantics RFC 9110 (accessed 2025-10-25T21:30:36-04:00): https://www.rfc-editor.org/rfc/rfc9110.html

Procedure

T1: Schema Validation (≤2k tokens)

Fast path for 80% of schema validation cases:

1. Parse input specification:

   • If api_spec provided: parse and validate syntax
   • If not provided: prepare empty schema template

2. Validate core schema elements (REST):

   • OpenAPI version ≥ 3.0.0
   • Info object (title, version, description) present
   • Paths object with at least one endpoint
   • HTTP methods use standard verbs (GET, POST, PUT, PATCH, DELETE)
   • Request/response schemas defined with JSON Schema
   • Status codes follow RFC 9110 semantics

3. Validate core schema elements (GraphQL):

   • Schema Definition Language (SDL) syntax valid
   • Query type defined
   • Object types have fields with valid scalars or references
   • No circular dependencies without proper resolution
   • Input types for mutations properly defined
   • Nullable/non-nullable annotations appropriate

4. Quick security checks:

   • Authentication mentioned in schema (securitySchemes for REST, directives for GraphQL)
   • Sensitive data (passwords, tokens) not in query parameters (REST)
   • HTTPS enforced (servers array for REST)

5. Generate validation report:

   • Syntax errors (critical)
   • Missing required elements (high)
   • Best practice violations (medium)
   • Recommendations (low)

Output: Schema validation report with severity-ranked findings

Token budget: ≤2k tokens (schema parsing + basic validation rules)

T2: Security Hardening & Design Patterns (≤6k tokens)

Extended validation with OWASP API Security Top 10 compliance:

1. Apply T1 validation first

2. OWASP API Security Top 10 2023 checks (accessed 2025-10-25T21:30:36-04:00):

   • API1:2023 Broken Object Level Authorization: Check for resource ID exposure without authorization checks
   • API2:2023 Broken Authentication: Validate authentication scheme (OAuth 2.0, JWT, API keys)
   • API3:2023 Broken Object Property Level Authorization: Verify sensitive fields have access controls
   • API4:2023 Unrestricted Resource Consumption: Check for rate limiting, pagination, max page size
   • API5:2023 Broken Function Level Authorization: Validate role-based access controls
   • API6:2023 Unrestricted Access to Sensitive Business Flows: Check for business logic flow protection
   • API7:2023 Server Side Request Forgery: Validate URL input sanitization
   • API8:2023 Security Misconfiguration: Check security headers, CORS, error verbosity
   • API9:2023 Improper Inventory Management: Verify API versioning and deprecation strategy
   • API10:2023 Unsafe Consumption of APIs: Validate third-party API input validation

3. REST-specific design patterns (accessed 2025-10-25T21:30:36-04:00):

   • Pagination: Cursor-based (recommended) vs offset-based
     • Cursor: /resources?cursor=xyz&limit=20
     • Offset: /resources?offset=40&limit=20
     • HAL links for navigation: _links.next.href
   • Filtering: Query parameters with standardized operators
     • /users?filter[status]=active&filter[role]=admin
   • Sorting: ?sort=-created_at,name (- prefix for descending)
   • Field selection: ?fields=id,name,email (sparse fieldsets)
   • Error handling: RFC 9457 Problem Details for HTTP APIs
   • Versioning:
     • Path: /v1/resources (most common, cache-friendly)
     • Header: Accept: application/vnd.api.v1+json (flexible)
     • Query: /resources?version=1 (least recommended)

4. GraphQL-specific design patterns (accessed 2025-10-25T21:30:36-04:00):

   • Pagination: Relay cursor connections specification
     • edges, node, pageInfo structure
     • hasNextPage, hasPreviousPage, startCursor, endCursor
   • Filtering: Input objects with typed arguments
   • Authorization: @auth directives or resolver-level checks
   • Error handling: Errors array with extensions for error codes
   • Batching: DataLoader pattern for N+1 query prevention
   • Depth limiting: Max query depth to prevent DoS
   • Cost analysis: Complexity scoring for expensive queries

5. Generate comprehensive outputs:

   • Schema: Valid OpenAPI 3.x or GraphQL SDL with security annotations
   • Validation report: OWASP API Security Top 10 mappings with remediation steps
   • Design patterns: Pagination, filtering, error handling implementations
   • Security recommendations: Prioritized action items with source citations

Output: Complete API design package with security-hardened schema and implementation guidance

Token budget: ≤6k tokens (T1 + OWASP checks + design patterns + 4-6 authoritative sources)

T3: Not Implemented

This skill implements T1 and T2 tiers only. For advanced scenarios requiring:

• Multi-API orchestration and gateway design
• Custom compliance framework mappings beyond OWASP
• API federation architecture (GraphQL Federation, API Gateway mesh)
• Advanced threat modeling specific to API attack vectors

Defer to:

• security-assessment-framework (T3) for comprehensive threat modeling
• microservices-pattern-architect for API gateway patterns
• GraphQL-federation-architect (Phase 3) for federated GraphQL schemas

Token budget: N/A (not implemented in this skill)

Decision Rules

Ambiguity thresholds:

• If api_type not specified: ABORT with error "api_type is required: REST or GraphQL"
• If schema syntax invalid: ABORT T2, return T1 syntax errors only
• If security requirements unclear: Default to strictest (authentication required, HTTPS enforced)

Tier selection:

• Use T1 if: Quick schema validation needed, no security audit required
• Use T2 if: Production-ready API, security compliance required, design patterns needed

Abort conditions:

• Invalid JSON/YAML structure for REST OpenAPI spec
• Invalid SDL syntax for GraphQL schema
• API type not recognized (not REST or GraphQL)

When to invoke dependent skills:

• If compliance framework mapping needed: Invoke security-assessment-framework (ref CLAUDE.md §3)
• If authentication architecture design needed: Defer to security-assessment-framework IAM domain

Output Contract

Schema types:

interface ValidationReport {
  api_type: "REST" | "GraphQL";
  tier: "T1" | "T2";
  status: "pass" | "fail" | "warning";
  findings: Finding[];
  schema?: object | string;  // OpenAPI object or GraphQL SDL string
  security_recommendations?: SecurityRecommendation[];
  design_patterns?: DesignPatterns;
}

interface Finding {
  severity: "critical" | "high" | "medium" | "low";
  category: "syntax" | "security" | "best-practice" | "performance";
  message: string;
  location?: string;  // JSON path or GraphQL type/field
  remediation?: string;
  owasp_mapping?: string;  // e.g., "API1:2023"
}

interface SecurityRecommendation {
  owasp_id: string;  // API1:2023 through API10:2023
  title: string;
  description: string;
  current_status: "compliant" | "non-compliant" | "unknown";
  action_items: string[];
  references: string[];
}

interface DesignPatterns {
  pagination?: object;
  filtering?: object;
  sorting?: object;
  error_handling?: object;
  versioning?: object;
}

Required fields:

• api_type, tier, status, findings (always)
• schema (if T2 or generation requested)
• security_recommendations, design_patterns (if T2)

Data validation:

• All severity levels must be from enum
• OWASP mappings must match 2023 edition identifiers
• References must be accessible URLs with access date = NOW_ET

Examples

Example 1: REST API validation (T1)

Input:
  api_type: "REST"
  api_spec:
    openapi: "3.1.0"
    info:
      title: "User API"
      version: "1.0"
    paths:
      /users:
        get:
          parameters:
            - name: password
              in: query
          responses:
            200:
              description: OK

Output:
  status: "fail"
  findings:
    - severity: "critical"
      category: "security"
      message: "Sensitive parameter 'password' in query string"
      location: "/paths/~1users/get/parameters/0"
      remediation: "Move to request body or header"
      owasp_mapping: "API8:2023"

Quality Gates

Token budgets (mandatory enforcement):

• T1: ≤2k tokens - Schema validation only, no heavy retrieval
• T2: ≤6k tokens - OWASP checks + design patterns + 4-6 authoritative sources
• T3: N/A - Not implemented (defer to dependent skills for advanced scenarios)

Safety:

• No API keys, credentials, or secrets in examples
• All external URLs verified accessible at NOW_ET
• No execution of untrusted API specifications

Auditability:

• All OWASP mappings cite 2023 edition with access date
• Design pattern recommendations cite authoritative sources (OpenAPI spec, GraphQL spec, RFCs)
• Schema generation follows official specifications only

Determinism:

• Same input specification produces same findings
• Severity rankings consistent across runs
• Schema validation rules non-probabilistic

Resources

Authoritative specifications (accessed 2025-10-25T21:30:36-04:00):

• OpenAPI 3.1.0: https://spec.openapis.org/oas/v3.1.0
• GraphQL Spec Oct 2021: https://spec.graphql.org/October2021/
• OWASP API Security Top 10 2023: https://owasp.org/API-Security/editions/2023/en/0x11-t10/
• HTTP Semantics RFC 9110: https://www.rfc-editor.org/rfc/rfc9110.html
• RFC 9457 Problem Details: https://www.rfc-editor.org/rfc/rfc9457.html
• Relay Cursor Connections: https://relay.dev/graphql/connections.htm

Best practices (accessed 2025-10-25T21:30:36-04:00):

• GraphQL Best Practices: https://graphql.org/learn/best-practices/
• Swagger/OpenAPI Best Practices: https://swagger.io/docs/specification/about/
• REST API Design: https://restfulapi.net/

Templates and schemas:

• See /skills/api-design-validator/resources/templates/ for OpenAPI starter templates
• See /skills/api-design-validator/resources/schemas/ for GraphQL schema examples

Security references:

• OWASP API Security Project: https://owasp.org/www-project-api-security/
• OWASP Cheat Sheet - REST Security: https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html
• OWASP Cheat Sheet - GraphQL: https://cheatsheetseries.owasp.org/cheatsheets/GraphQL_Cheat_Sheet.html