SIDDARTHA577/envguard-node / .agents/skills/envguard-api-design
envguard-api-design
VerifiedGuides the specification and design of standardized RESTful APIs with OpenAPI 3.1 contracts, explicit HTTP semantics, RFC 7807 structured error responses, pagination, filtering, and backward compatibility.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
SKILL.md
View on GitHub---
name: envguard-api-design
description: Guides the specification and design of standardized RESTful APIs with OpenAPI 3.1 contracts, explicit HTTP semantics, RFC 7807 structured error responses, pagination, filtering, and backward compatibility.
---
# `envguard-api-design` Skill
Guides engineers and AI agents in architecting, documenting, and validating production-grade RESTful API contracts. Enforces clear HTTP semantics, schema-driven validation, structured error reporting via RFC 7807 / RFC 9457 Problem Details, robust pagination, and backward compatibility.
## When to Trigger
- Designing, documenting, or refactoring RESTful API endpoints, request schemas, and response shapes.
- Creating or updating OpenAPI 3.0 / 3.1 specifications, JSON Schema contracts, or TypeBox/Zod validation schemas.
- Standardizing HTTP status codes, method semantics (GET, POST, PUT, PATCH, DELETE), and resource URL paths.
- Implementing structured error response envelopes compliant with RFC 7807 / RFC 9457 Problem Details.
- Defining query parameters for collection endpoints including pagination (cursor vs offset), sorting, and filtering.
- Reviewing API changes for breaking modifications, field deprecation, and backward-compatible versioning.
## When NOT to Trigger
- Writing low-level database queries, SQL migrations, or connection pools (use `envguard-database`).
- Implementing client-side React components, CSS styling, or JSX templates (use `envguard-frontend` or `envguard-ui-design`).
- Configuring CI/CD deployment pipelines or infrastructure orchestration (use `envguard-ci` or `envguard-devops`).
- Validating raw environment variables at server boot (use `envguard-setup` or `envguard-review`).
## Supported Projects & Environments
- Runtimes: Node.js (22.x, 24.x, 26.x), Bun, Deno, Edge runtimes.
- Frameworks: Express, Fastify, NestJS, Koa, Hono, Next.js API Routes.
- Specifications: OpenAPI 3.0 / 3.1, JSON Schema Draft 7 / 2020-12, AsyncAPI.
- Schema Validators: EnvGuard (`guard()`), Zod, TypeBox, Valibot, Joi.
- Documentation Formats: Swagger UI, Redoc, Stoplight Elements.
## Required Tools & Permissions
- Tools: File reader, file writer, test runner (`read_file`, `write_file`, `run_command`).
- Permissions: Project workspace read and write permissions to inspect, create, and update route definitions, API specifications, and contract test fixtures.
## Expected Inputs
- Target resource entities and domain models (e.g. `User`, `Task`, `Workspace`, `Organization`).
- Business actions required on resources (create, retrieve, list, update, patch, soft/hard delete).
- Existing API routing codebase or OpenAPI specification documents.
## Step-by-Step Workflow
### Step 1: Resource Modeling & URL Hierarchy
- Name resources using plural lowercase nouns: `/api/v1/tasks`, `/api/v1/users`, `/api/v1/projects`.
- Model sub-resources hierarchically only when parent ownership is strictly dependent:
- `/api/v1/projects/{projectId}/tasks`
- Avoid nesting deeper than two levels (e.g. `/api/v1/orgs/{orgId}/projects/{projId}/teams/{teamId}/members` is an anti-pattern; flatten to `/api/v1/teams/{teamId}/members`).
- Keep URLs clean and free of RPC action verbs:
- Use `POST /api/v1/tasks` (NOT `/api/v1/createTask`).
- Use `DELETE /api/v1/tasks/{id}` (NOT `/api/v1/deleteTaskById?id=123`).
- For non-CRUD state transitions, use sub-resource actions: `POST /api/v1/tasks/{id}/archive` or `POST /api/v1/tasks/{id}/publish`.
### Step 2: HTTP Method Semantics & Status Codes
- Strictly enforce standard HTTP methods and expected response codes:
- `GET`: Safe and idempotent. Return `200 OK` with payload, or `404 Not Found` if entity missing.
- `POST`: Non-idempotent creation or action. Return `201 Created` with `Location` header, or `200 OK` / `202 Accepted` for asynchronous tasks.
- `PUT`: Idempotent full replacement of the resource. Return `200 OK` or `204 No Content`.
- `PATCH`: Partial resource modification. Return `200 OK` with the updated resource representation.
- `DELETE`: Idempotent deletion. Return `204 No Content` on success, or `200 OK` if returning tombstone details.
- Avoid the anti-pattern of returning `200 OK` with `{ "success": false, "error": "..." }`. Failures MUST use appropriate 4xx/5xx status codes.
### Step 3: Standardized Error Responses (RFC 7807 / RFC 9457)
- Structure all error responses using Problem Details standard (`application/problem+json`):
```json
{
"type": "https://api.example.com/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"detail": "The request body contains invalid parameter values.",
"instance": "/api/v1/tasks/123",
"invalidParams": [
{
"name": "priority",
"reason": "Must be one of ['low', 'medium', 'high', 'urgent']"
}
],
"traceId": "req-9f20e4b"
}
```
- **Rule**: Never expose raw stack traces, SQL syntax errors, internal filesystem paths, or database connection strings in error payloads.
### Step 4: Collection Query Standards (Pagination, Filtering, Sorting)
- Support structured collection pagination:
- **Cursor-based (Recommended for high volume)**: `?limit=25&cursor=eyJpZCI6MTAwfQ` -> returns `{ "data": [...], "pagination": { "nextCursor": "...", "hasMore": true } }`.
- **Offset-based (Simple tabular data)**: `?page=1&limit=25` -> returns `{ "data": [...], "pagination": { "page": 1, "limit": 25, "total": 140, "totalPages": 6 } }`.
- Cap maximum page size (e.g. `limit` maximum 100) to prevent denial-of-service via unbounded queries.
- Sorting: `?sort=-createdAt,priority` (prefix `-` signifies descending order).
- Filtering: Explicit field matches (e.g. `?status=open&priority=high`).
### Step 5: OpenAPI 3.1 Specification Authoring
- Author or update OpenAPI 3.1 schemas with full documentation:
- `info`: Title, version, description, license.
- `servers`: Environment URLs (`https://api.example.com/v1`, `http://localhost:3000/v1`).
- `paths`: Method definitions with `operationId`, `summary`, `tags`, `parameters`, `requestBody`, and `responses`.
- `components.schemas`: Reusable data models with `type`, `properties`, `required`, and sample values.
- `components.securitySchemes`: Bearer tokens, OAuth2 flows, or API keys.
### Step 6: Backward Compatibility & Versioning
- Enforce backward-compatible evolution rules:
- **Non-breaking**: Adding new endpoints, adding optional request fields, adding new response fields.
- **Breaking**: Renaming fields, changing field types, removing fields, adding mandatory request parameters, altering status codes.
- When breaking changes are unavoidable, introduce a new major API version prefix (e.g. `/v2/`) and maintain the `/v1/` endpoint with deprecation headers (`Sunset`, `Deprecation`).
## Validation Steps
- Validate OpenAPI spec files using schema validation tools or linting (`spectral lint` or internal schema validator).
- Verify that every endpoint has explicit 4xx and 5xx error responses documented.
- Verify that all collection endpoints document pagination constraints and maximum page sizes.
- Verify that zero endpoints return `200 OK` when encountering validation or authorization errors.
## Expected Outputs
- Valid OpenAPI 3.1 document (`openapi.json` or `openapi.yaml`).
- TypeScript request and response interface definitions matching the API schema.
- Route controller specifications adhering to HTTP verb and status code standards.
- Problem Details error formatting middleware/utility.
## Failure Handling
- If legacy endpoints violate REST conventions, provide an adapter facade and establish deprecation timelines rather than immediately breaking client integrations.
- If payload schemas conflict with database types, introduce distinct Data Transfer Objects (DTOs) with mapping functions.
## Safety & Privacy Boundaries
- Never accept unvalidated JSON bodies directly into database queries; always validate schemas first.
- Never document sensitive environment variables, internal infrastructure IPs, or administrative credentials in public OpenAPI specs.
- Sensitive fields (passwords, tokens, SSNs) must be marked `writeOnly: true` in schemas and excluded from response representations.
## Example User Prompts
- "Design a RESTful API contract for our task management service with envguard-api-design"
- "Generate an OpenAPI 3.1 specification for our user and organization endpoints"
- "Standardize error handling and pagination across all backend routes to RFC 7807"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |