feature-api_skill

Overview

This skill helps design and implement HTTP APIs for new features, covering endpoints, schemas, error handling, versioning, and rate limits. It produces a clear implementation status report and actionable checks to ensure compatibility and operability. Use it to validate new API work before release or integration testing.

How this skill works

The skill inspects endpoint design, request and response schemas, error handling, and versioning practices against a checklist of best practices. It verifies naming, parameter usage, idempotency, pagination, content negotiation, and rate limiting, then outputs a status (Complete, Partial, Blocked, Skipped) for each area. It highlights compatibility risks and recommends remediation steps for breaking changes or missing tests.

When to use it

• Designing new REST endpoints for a feature
• Reviewing API contracts before integration with consumers
• Preparing a public API or third-party integration
• Auditing backward compatibility and versioning plans
• Assessing error classification and retry behavior

Best practices

• Use consistent resource naming and HTTP methods aligned with RESTful conventions
• Distinguish path vs query parameters and document required fields clearly
• Ensure PUT/DELETE operations are idempotent and document side effects
• Standardize response envelopes, date/time formats, and pagination structure
• Define a clear versioning strategy and provide deprecation notices for breaking changes
• Use structured error codes, appropriate 4xx/5xx status codes, and non-sensitive error messages

Example use cases

• Designing CRUD endpoints for a new product catalog service with pagination
• Reviewing an authentication API for consistent error responses and retry-safe classifications
• Validating a v2 API rollout: compatibility checks and migration path planning
• Setting rate limits and throttling rules for a high-traffic public endpoint
• Creating integration contract tests to ensure consumer compatibility before deployment