skills.rest
guardiatechnology
guardiatechnologyOFFICIAL
Explore all skills by this author →
WebsiteGitHub

kata-api-design-review

Review RESTful HTTP API contracts for Guardia Lexis and Codex compliance.

Updated Sep 3, 2025
Search Tags:#authentication#error handling#api design#idempotency#pagination#rest compliance#openapi review
One-click install
npx skills add https://github.com/guardiatechnology/design-system --skill kata-api-design-review
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: kata-api-design-review
Source: https://github.com/guardiatechnology/design-system/tree/main/.claude/skills/kata-api-design-review
Command: npx skills add https://github.com/guardiatechnology/design-system --skill kata-api-design-review

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps teams detect REST API contract violations early by checking endpoint semantics, entity schemas, idempotency, errors, authentication, and pagination/sorting against Guardia Lexis and Codex.

Core Features & Use Cases

  • Contract compliance review across existing HTTP API contracts to ensure RESTful consistency and rule alignment.
  • Endpoint validation for paths, methods, allowed status codes, and (for OpenAPI) operation ordering within each path.
  • Schema and behavior checks covering entity fields, mutation idempotency via Idempotency-Key, standardized error payload structure, authentication requirements, and pagination/sorting conventions.

Quick Start

Tell the AI to review the contract at the path you provide and return a structured Markdown report with a clear verdict and fix recommendations for any ERRORs or WARNINGs.

Frequently Asked Questions about kata-api-design-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review my OpenAPI contract for REST compliance and idempotency issues?▼

To review OpenAPI contracts for REST compliance, provide the contract path. The audit checks endpoint semantics, entity schemas, idempotency-key behavior, and pagination, returning a structured Markdown findings table with ERROR or WARNING classifications.

What is the best way to audit HTTP API authentication and error handling against standard rules?▼

Auditing HTTP API authentication and error handling involves validating standardized error payload structures and auth requirements against Guardia Lexis and Codex. The process generates a structured Markdown report summarizing deviations and compliance counts.

Can I use Markdown files to validate API endpoint semantics and pagination sorting conventions?▼

Yes, you can validate API endpoint semantics and pagination sorting conventions using Markdown contracts. The review process applies Guardia Lexis and Codex rules to Markdown files just as it does with OpenAPI 3.x specifications.

How do I get fix recommendations for RESTful API contract violations found during a review?▼

To get fix recommendations for RESTful API contract violations, you must explicitly request fix mode during the review. Otherwise, the process outputs only a structured Markdown report with a clear verdict and classified findings.

What distinguishes an ERROR from a WARNING when checking API paths and allowed status codes?▼

When checking API paths and allowed status codes, an ERROR indicates a violation of Guardia Lexis rules, while a WARNING signifies a deviation from Guardia Codex standards. Both are counted in the final summary report.

Related Skills

Explore More Legal & Compliance Skills→
epieczkoepieczko

api.validate

Validate OpenAPI 3.x and AsyncAPI 3.x specifications against Zalando guidelines.

Community
Intermediate
lamb92009lamb92009

api-designer

Design REST and GraphQL APIs and generate OpenAPI 3.1 specifications.

Community
Advanced
infraspecdevinfraspecdev
3

backend-api-design-review

Review HTTP and GraphQL API design for correctness and consistency.

Official
Intermediate
guardiatechnologyguardiatechnology

kata-api-design-oas

Generate OpenAPI 3.x YAML specifications for RESTful API features.

Official
Intermediate