api-expert_skill

Overview

This skill is an API architecture expert focused on designing secure, scalable, and consistent APIs using REST, GraphQL, and gRPC. It emphasizes OpenAPI 3.1 contract-driven design, robust authentication patterns (OAuth2.1, JWT), and OWASP API Security Top 10 mitigations. Use it to produce production-ready API contracts, gateway patterns, and security controls.

How this skill works

I inspect existing API contracts, implementation patterns, and security posture, then produce concrete designs: OpenAPI 3.1 specs, endpoint semantics, authentication flows, rate-limiting strategies, and RFC 7807 error formats. I follow a verification-first protocol—validate standards, confirm status codes, and cite authoritative sources when uncertainty exceeds 20%. Outputs include tests-first examples, gateway rules, and implementation checklists.

When to use it

• Design or refactor RESTful or GraphQL APIs to be consistent and discoverable
• Create or validate OpenAPI 3.1 specifications and contract tests
• Implement authentication and authorization (OAuth2.1, JWT, mTLS) securely
• Define rate limiting, pagination, and caching strategies for scale
• Design API gateway policies, security scans, and error handling templates
• Audit APIs against OWASP API Security Top 10 and remediation plans

Best practices

• Start with failing contract tests (TDD) and validate against OpenAPI 3.1 before coding
• Use proper HTTP semantics and RFC-verified status codes; avoid always returning 200
• Follow ‘security by default’: short JWT lifetimes, token revocation, and scope-based auth
• Implement efficient pagination (cursor/keyset) and set sane defaults and hard limits
• Expose consistent RFC 7807 problem details with correlation IDs; never leak internals
• Use distributed rate limiting with Retry-After and X-RateLimit headers; document quotas

Example use cases

• Produce an OpenAPI 3.1 spec and contract tests for a new /v1/users service
• Design gateway rules for rate limiting, caching, and OAuth2 token validation
• Create JWT validation middleware with revocation checks and scope enforcement
• Migrate offset pagination endpoints to cursor-based pagination with HATEOAS links
• Audit an API surface for OWASP API Top 10 issues and provide prioritized fixes