rest-api-architect

Files (1)

• SKILL.md

SKILL.md (first lines)

# Context
Use this skill when:
1. Designing new API endpoints or resources.
2. Reviewing existing OpenAPI (`swagger.yaml/json`) files.
3. Generating boilerplate code from an API contract.

# Design Principles

### 1. Resource-First Naming
- **Nouns Only:** Use `/users`, not `/getUsers`. Actions are defined by HTTP methods.
- **Plurality:** Use plural nouns for collections (`/orders`) and IDs for instances (`/orders/{id}`).
- **Case:** All paths MUST be `kebab-case` and lowercase.

### 2. Semantic HTTP Methods
- `GET`: Idempotent retrieval. No side effects.
- `POST`: Create a new resource or trigger a non-idempotent action.
- `PUT`: Full replacement of a resource (Idempotent).
- `PATCH`: Partial update (Preferred over PUT for performance).
- `DELETE`: Remove a resource.

### 3. Standardization (OpenAPI 3.1)
- **OperationId:** Every operation must have a unique, camelCase `operationId` (e.g., `listUsers`).
- **Descriptions:** Every parameter, property, and response must have a `description` field for AI discoverability.
- **Status Codes:** - `201 Created` for successful POSTs.
  - `422 Unprocessable Entity` for validation errors (Standard in 2026).
  - `429 Too Many Requests` for rate-limiting.
- **Error Format:** Follow **RFC 9457** (Problem Details for HTTP APIs).

### 4. Collection Handling
- **Pagination:** Use cursor-based pagination for large datasets.
- **Filtering:** Use query parameters (e.g., `/products?category=tech`).
- **Sorting:** Use a standardized `sort` parameter (e.g., `?sort=-created_at`).

# Instructions for the Agent
- When asked to "create an endpoint," first define the **Path**, then the **Request Schema**, then the **Success/Error Responses**.
- Always use `$ref` to keep schemas modular and reusable in `components/schemas`.
- Ensure all Date/Time fields use `format: date-time` (ISO 8601).

From vivek-viswanat/dev-arsenal, MIT.

More from vivek-viswanat/dev-arsenal