Api contract validation

Skill Babalsaab/Project_Starter/skills/api-contract-validation

Use when validating API designs, checking REST/GraphQL conventions, reviewing naming consistency, versioning, error handling, pagination, or backward compatibility.From its SKILL.md

Install

npx -y skills add Babalsaab/Project_Starter --skill api-contract-validation

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.0 KB, as published. Nobody here has run it

# API Contract Validation

When designing, reviewing, or consuming APIs, enforce these standards:

## REST API Conventions

### URL Design
- Use plural nouns for resources: `/users`, `/orders`, `/products`
- Use path params for identity: `/users/{id}`
- Use query params for filtering: `/users?role=admin&status=active`
- Nest for relationships: `/users/{id}/orders` (max 2 levels deep)
- Use kebab-case for multi-word paths: `/order-items`
- Version in URL path: `/api/v1/users` or via `Accept` header

### HTTP Methods
| Method | Purpose | Idempotent | Response |
|--------|---------|------------|----------|
| GET | Read resource(s) | Yes | 200 + body |
| POST | Create resource | No | 201 + Location header |
| PUT | Full replace | Yes | 200 + body |
| PATCH | Partial update | No | 200 + body |
| DELETE | Remove resource | Yes | 204 (no body) |

### Status Codes
- **2xx**: 200 OK, 201 Created, 204 No Content
- **3xx**: 301/302 Redirect (only for URL changes)
- **4xx**: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests
- **5xx**: 500 Internal Server Error, 503 Service Unavailable

### Error Response Format
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "issue": "Invalid email format" }
    ],
    "request_id": "req_abc123"
  }
}

Naming Conventions

Request/response fields: camelCase
Consistent naming: if created_at exists, don't introduce updatedTime
Boolean fields prefixed: isActive, hasOrders, canEdit
Date/time fields: ISO 8601 format (2024-01-15T10:30:00Z)
Enum values: UPPER_SNAKE_CASE

Pagination

Always paginate list endpoints:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Prefer cursor-based for large datasets:

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}

Versioning & Backward Compatibility

Breaking Changes (NEVER in minor version)

Removing a field from response
Renaming a field
Changing a field's type
Removing an endpoint
Adding required request fields

Non-Breaking Changes (safe in minor version)

Adding optional request fields
Adding response fields
Adding new endpoints
Adding new enum values (if client handles unknown)

Deprecation Process

Add Deprecation header with sunset date
Document replacement in API docs
Log usage of deprecated endpoints
Remove after sunset date (major version bump)

Security

Require authentication on all mutating endpoints
Rate limit all endpoints (especially auth)
Validate and sanitize all input
Never expose internal IDs or stack traces
Use HTTPS only — reject HTTP
Include request ID in all responses for tracing

Output Format

## API Contract Report

### Compliance: [PASS | WARNINGS | VIOLATIONS]

### Endpoints Reviewed
| Endpoint | Method | Issues |
|----------|--------|--------|
| /api/v1/users | GET | 0 |
| /api/v1/users | POST | 2 |

### Violations
| # | Severity | Rule | Endpoint | Description | Fix |
|---|----------|------|----------|-------------|-----|
| 1 | HIGH | Error Format | POST /users | Non-standard error body | Use standard error envelope |

### Breaking Changes Detected
- [ ] None / [ ] List...

### Recommendations
1. ...