Initial commit

skills/spec-author/templates/api-contract.md

@@ -0,0 +1,210 @@
+# API Contract Specification
+
+**Document ID:** `api-[feature]-[id]-[name]`
+**Status:** <!-- TODO: Draft | In Review | Approved | Deprecated -->
+**Owner:** <!-- TODO: Team/Individual Name -->
+**Last Updated:** <!-- TODO: YYYY-MM-DD -->
+
+## Overview
+
+**Purpose:** <!-- TODO: Brief description of API's purpose and primary use cases -->
+
+**Base URL:** <!-- TODO: e.g., `https://api.example.com/v1` -->
+
+**API Version:** <!-- TODO: e.g., v1 -->
+
+**Stability:** <!-- TODO: Stable | Beta | Experimental -->
+
+## Authentication
+
+**Method:** <!-- TODO: API Key | OAuth 2.0 | JWT | Basic Auth -->
+
+**Implementation:**
+<!-- TODO: Document authentication implementation, e.g.:
+```http
+Authorization: Bearer {token}
+```
+-->
+
+**Token Acquisition:** <!-- TODO: Brief description of how clients obtain credentials -->
+
+**Scopes/Permissions:** <!-- TODO: List required permissions if applicable -->
+
+## Rate Limiting
+
+**Limits:**
+<!-- TODO: Define rate limits for different tiers, e.g.:
+- Anonymous: X requests/minute
+- Authenticated: Y requests/minute
+- Premium: Z requests/minute
+-->
+
+**Headers:**
+<!-- TODO: Document rate limit headers, e.g.:
+```http
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1234567890
+```
+-->
+
+**Exceeded Limit Response:** <!-- TODO: Document behavior when rate limit exceeded, e.g., HTTP 429 with Retry-After header -->
+
+## Endpoints
+
+### <!-- TODO: Resource Name -->
+
+#### <!-- TODO: List [Resources] -->
+```http
+GET /<!-- TODO: endpoint path -->
+```
+
+**Query Parameters:**
+<!-- TODO: Document query parameters in table format:
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `param1` | type | Yes/No | Description |
+-->
+
+**Response:** <!-- TODO: Status code, e.g., `200 OK` -->
+<!-- TODO: Document response format:
+```json
+{
+  "data": [],
+  "pagination": {}
+}
+```
+-->
+
+#### <!-- TODO: Get [Resource] -->
+```http
+GET /<!-- TODO: endpoint path with parameter -->
+```
+
+**Path Parameters:**
+<!-- TODO: Document path parameters:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | Description |
+-->
+
+**Response:** <!-- TODO: Status code and example response -->
+
+#### <!-- TODO: Create [Resource] -->
+```http
+POST /<!-- TODO: endpoint path -->
+```
+
+**Request Body:**
+<!-- TODO: Document request body schema:
+```json
+{
+  "field": "value"
+}
+```
+-->
+
+**Response:** <!-- TODO: Status code and example response -->
+
+#### <!-- TODO: Update [Resource] -->
+```http
+PUT /<!-- TODO: endpoint path -->
+PATCH /<!-- TODO: endpoint path -->
+```
+
+**Request Body:** <!-- TODO: Document request body requirements -->
+
+**Response:** <!-- TODO: Status code and example response -->
+
+#### <!-- TODO: Delete [Resource] -->
+```http
+DELETE /<!-- TODO: endpoint path -->
+```
+
+**Response:** <!-- TODO: Status code, e.g., `204 No Content` -->
+
+## Data Models
+
+### <!-- TODO: Model Name -->
+<!-- TODO: Document data model fields:
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Unique identifier |
+| `field` | type | Yes/No | Description |
+-->
+
+**Constraints:**
+<!-- TODO: Document validation rules and constraints:
+- Constraint description
+-->
+
+## Error Handling
+
+**Error Response Format:**
+<!-- TODO: Document error response structure:
+```json
+{
+  "error": {
+    "code": "error_code",
+    "message": "Error message",
+    "details": [],
+    "request_id": "req_id"
+  }
+}
+```
+-->
+
+**Standard Error Codes:**
+<!-- TODO: Document error codes:
+| HTTP Status | Error Code | Description |
+|-------------|------------|-------------|
+| 400 | `validation_error` | Invalid request data |
+| 401 | `authentication_error` | Missing or invalid credentials |
+-->
+
+## Pagination
+
+<!-- TODO: Document pagination approach (offset-based, cursor-based, etc.):
+**Offset-Based Pagination:**
+```http
+GET /resources?limit=20&offset=40
+```
+
+**Response Format:**
+```json
+{
+  "data": [],
+  "pagination": {
+    "total": 100,
+    "limit": 20,
+    "offset": 40
+  }
+}
+```
+-->
+
+## Webhooks
+
+<!-- TODO: OPTIONAL - Remove this section if webhooks are not applicable
+
+**Supported Events:**
+- Event description
+
+**Webhook Payload:**
+```json
+{
+  "id": "evt_id",
+  "type": "event.type",
+  "data": {}
+}
+```
+
+**Endpoint Requirements:**
+- Requirement description
+
+**Signature Verification:**
+- Verification method
+
+**Retry Policy:**
+- Retry strategy
+-->