From c98d296fc58804df62f0ee09bec234f7e121fff7 Mon Sep 17 00:00:00 2001
From: Jordan Robinson <hello@jordanrobinson.org>
Date: Sun, 19 Oct 2025 15:34:15 +0100
Subject: [PATCH] add API documentation template

---
 README.md                      |   1 +
 templates/api-documentation.md | 135 +++++++++++++++++++++++++++++++++
 2 files changed, 136 insertions(+)
 create mode 100644 templates/api-documentation.md

diff --git a/README.md b/README.md
index 0e8c8bb33619f8a8339949be14552010831649f4..8f82a7019f62dd0cfbdc06e69b96e459455fd05a 100644
--- a/README.md
+++ b/README.md
@@ -8,3 +8,4 @@ Comprehensive collection of templates for solutions design, architecture decisio
 * Bug Fix
 * Performance Optimisation
 * Architecture Decision Record (ADR)
+* API Documentation
\ No newline at end of file
diff --git a/templates/api-documentation.md b/templates/api-documentation.md
new file mode 100644
index 0000000000000000000000000000000000000000..ca7abec465bbfc72d5b54a448e36644d31306ca2
--- /dev/null
+++ b/templates/api-documentation.md
@@ -0,0 +1,135 @@
+# API Documentation
+
+## API Overview
+**Name:** [API name]  
+**Version:** [Version]  
+**Base URL:** [URL]  
+**Status:** [Active/Deprecated/Beta]  
+**Last Updated:** [Date]
+
+## Authentication
+- Authentication method (OAuth2, API key, JWT, etc.)
+- How to obtain credentials
+- Token expiration and refresh
+- Example authentication headers
+
+## Rate Limiting
+- Rate limit thresholds (requests per minute/hour)
+- How limits are enforced
+- Rate limit headers returned
+- Handling 429 responses
+- Quota considerations
+
+## Error Handling
+- Standard error response format
+- HTTP status codes used
+- Common error codes and meanings
+- Retry logic recommendations
+- Troubleshooting guide
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable message",
+    "details": {}
+  }
+}
+```
+
+## Versioning Strategy
+- How versions are managed (URL path, header, query param)
+- Deprecation policy and timeline
+- Breaking change notifications
+- Backward compatibility guarantees
+
+## Endpoints
+
+### Endpoint: [METHOD] /resource/{id}
+**Description:** [What this endpoint does]  
+**Authentication:** [Required/Optional/None]  
+**Rate Limit:** [Tier if applicable]
+
+**Request**
+```
+Method: [GET/POST/PUT/DELETE/PATCH]
+Path: /v1/resource/{id}
+Query Parameters:
+  - param1 (string, required): Description
+  - param2 (integer, optional): Description
+
+Headers:
+  - Authorization: Bearer {token}
+  - Content-Type: application/json
+
+Body:
+{
+  "field1": "value",
+  "field2": 123
+}
+```
+
+**Response**
+```
+Success (200):
+{
+  "id": "resource-123",
+  "field1": "value",
+  "field2": 123,
+  "createdAt": "2025-01-15T10:30:00Z"
+}
+
+Error (400):
+{
+  "error": {
+    "code": "INVALID_REQUEST",
+    "message": "Missing required field: field1"
+  }
+}
+```
+
+**Status Codes:**
+- 200: Success
+- 400: Bad request
+- 401: Unauthorized
+- 403: Forbidden
+- 404: Not found
+- 429: Rate limit exceeded
+- 500: Server error
+
+**Examples:**
+```
+curl -X GET https://api.example.com/v1/resource/123 \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
+  -H "Content-Type: application/json"
+```
+
+## Webhooks (if applicable)
+- Supported events
+- Payload format
+- Retry logic
+- Signing/verification
+- Example webhook payloads
+
+## Pagination
+- Pagination style (offset/limit, cursor, keyset)
+- Maximum page size
+- Default page size
+- Example paginated response
+
+## Filtering & Sorting
+- Supported filter operators
+- Sortable fields
+- Query syntax examples
+
+## SDK & Client Libraries
+- Available SDKs
+- Installation instructions
+- Links to repositories
+
+## Changelog
+- Version history
+- Breaking changes
+- New features
+- Bug fixes
+- Deprecations
\ No newline at end of file