# Api Contract

> Generate or validate OpenAPI and AsyncAPI specs from code or requirements with consistent naming, errors, and pagination

- **Type:** Skill
- **Install:** `agentstack add skill-weisser-dev-awesome-opencode-api-contract`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [weisser-dev](https://agentstack.voostack.com/s/weisser-dev)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [weisser-dev](https://github.com/weisser-dev)
- **Source:** https://github.com/weisser-dev/awesome-opencode/tree/main/templates/skills/api-contract
- **Website:** https://www.npmjs.com/package/@weisser-dev/awesome-opencode

## Install

```sh
agentstack add skill-weisser-dev-awesome-opencode-api-contract
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## What I do

- Generate OpenAPI 3.x or AsyncAPI specs from code or requirements
- Validate existing API specs for completeness and consistency
- Enforce consistent naming conventions across endpoints
- Standardize error response formats and HTTP status codes
- Define pagination, filtering, and sorting patterns

## When to use me

Use this skill when you need to:
- Design a new REST or async API from requirements
- Generate an OpenAPI spec from existing route handlers
- Validate an existing spec for consistency and completeness
- Standardize error responses across an API
- Add pagination to collection endpoints

## Process

1. **Discover**: Analyze existing API code or requirements
   - Scan route definitions, controllers, and handler files
   - Identify existing OpenAPI/Swagger specs if present
   - Note current naming conventions and response patterns

2. **Design resource model**: Map domain entities to API resources
   - Use plural nouns for collection endpoints (`/users`, `/orders`)
   - Use nested routes for relationships (`/users/{id}/orders`)
   - Avoid verbs in URLs; use HTTP methods for actions

3. **Define endpoints**: Specify each operation
   - HTTP method and path
   - Request parameters (path, query, header, body)
   - Request body schema with required fields
   - Response schemas for each status code
   - Authentication requirements

4. **Standardize patterns**: Apply consistent conventions

5. **Generate spec**: Produce the OpenAPI/AsyncAPI document

6. **Validate**: Check spec for completeness and correctness

## Naming Conventions

| Element | Convention | Example |
|---------|-----------|---------|
| Paths | kebab-case, plural nouns | `/api/v1/user-accounts` |
| Query params | camelCase | `?pageSize=20&sortBy=createdAt` |
| Request/response fields | camelCase | `{ "firstName": "Jane" }` |
| Schema names | PascalCase | `UserAccount`, `OrderItem` |
| Enum values | UPPER_SNAKE_CASE | `"ORDER_PENDING"` |

## Standard Error Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      }
    ],
    "requestId": "req_abc123"
  }
}
```

### HTTP Status Code Usage

| Code | Usage |
|------|-------|
| 200 | Successful GET, PUT, PATCH |
| 201 | Successful POST that creates a resource |
| 204 | Successful DELETE with no response body |
| 400 | Validation error or malformed request |
| 401 | Missing or invalid authentication |
| 403 | Authenticated but insufficient permissions |
| 404 | Resource not found |
| 409 | Conflict (duplicate, state violation) |
| 422 | Semantically invalid request |
| 429 | Rate limit exceeded |
| 500 | Unexpected server error |

## Pagination Pattern

```yaml
# Query parameters
parameters:
  - name: page
    in: query
    schema:
      type: integer
      minimum: 1
      default: 1
  - name: pageSize
    in: query
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 20

# Response envelope
PagedResponse:
  type: object
  properties:
    data:
      type: array
      items: { $ref: '#/components/schemas/Item' }
    pagination:
      type: object
      properties:
        page: { type: integer }
        pageSize: { type: integer }
        totalItems: { type: integer }
        totalPages: { type: integer }
```

## Validation Checklist

- [ ] All endpoints have descriptions
- [ ] All request parameters have types and constraints
- [ ] All responses include schema definitions
- [ ] Error responses follow the standard format
- [ ] Collection endpoints support pagination
- [ ] Authentication requirements specified per endpoint
- [ ] Examples provided for request and response bodies
- [ ] No breaking changes from previous spec version (if updating)

## Rules

- Always version the API in the URL path (`/api/v1/...`)
- Use JSON as the default content type
- Include `requestId` in all error responses for traceability
- Define rate limiting headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`)
- Document all enum values explicitly in the schema
- Prefer `$ref` for reusable schemas over inline definitions

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [weisser-dev](https://github.com/weisser-dev)
- **Source:** [weisser-dev/awesome-opencode](https://github.com/weisser-dev/awesome-opencode)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/@weisser-dev/awesome-opencode

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-weisser-dev-awesome-opencode-api-contract
- Seller: https://agentstack.voostack.com/s/weisser-dev
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.