api-design-validator_skill

Overview

This skill validates and hardens REST and GraphQL APIs by generating OpenAPI or GraphQL schemas, running schema checks, and mapping findings to OWASP API Security Top 10 guidance. It produces severity-ranked validation reports, security recommendations, and optional generated schemas ready for documentation or implementation. Use it to catch schema errors, enforce API design patterns, and prepare APIs for production security reviews.

How this skill works

The skill parses an input API specification (OpenAPI JSON/YAML for REST or SDL for GraphQL) or builds a starter template when none is provided. It runs a T1 fast-path for schema and basic security checks, and a T2 extended pass that applies OWASP API Security Top 10 checks and platform-specific design patterns. Outputs include a ValidationReport with findings, remediation steps, design pattern guidance, and an annotated schema when requested.

When to use it

• Designing new REST or GraphQL endpoints and generating canonical schemas
• Validating an existing API before deployment or security audit
• Ensuring compliance with OWASP API Security Top 10 2023
• Standardizing pagination, filtering, sorting, and error handling patterns
• Defining a backwards-compatible versioning strategy and deprecation plan

Best practices

• Enforce OpenAPI >= 3.0.0 for REST and valid SDL for GraphQL before deeper checks
• Prefer cursor-based pagination for large collections and Relay connections for GraphQL
• Apply authentication and authorization checks at both endpoint and field levels
• Use RFC 9457 Problem Details for consistent HTTP error responses
• Enforce HTTPS, avoid sensitive data in query strings, and set security headers

Example use cases

• Run T1 quick validation to find syntax errors and missing info fields in an OpenAPI file
• Run T2 security hardening on a production API to get OWASP-mapped remediation actions
• Generate an OpenAPI 3.x spec with securitySchemes and documented pagination/filtering
• Validate a GraphQL SDL for depth limits, DataLoader patterns, and @auth usage
• Assess versioning strategy (path, header, query) and recommend migration steps