job-forge/.claude/templates/api-docs.md

API Endpoint: [Method] [Endpoint Path]

Overview

Brief description of what this endpoint does and when to use it.

Authentication

• Required: Yes/No
• Type: Bearer Token / API Key / None
• Permissions: List required permissions

Request

HTTP Method & URL

[METHOD] /api/v1/[endpoint]

Headers

Content-Type: application/json
Authorization: Bearer <your-token>

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier

Query Parameters

Parameter	Type	Required	Default	Description
page	number	No	1	Page number for pagination
limit	number	No	20	Number of items per page

Request Body

{
  "field1": "string",
  "field2": "number", 
  "field3": {
    "nested": "object"
  }
}

Request Schema

Field	Type	Required	Validation	Description
field1	string	Yes	1-100 chars	Field description
field2	number	No	> 0	Field description

Response

Success Response (200/201)

{
  "success": true,
  "data": {
    "id": "uuid",
    "field1": "string",
    "field2": "number",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5
    }
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Something went wrong"
  }
}

Rate Limiting

• Limit: 1000 requests per hour per user
• Headers:
  • X-RateLimit-Limit: Total requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Reset time (Unix timestamp)

Examples

cURL Example

curl -X [METHOD] "https://api.yourdomain.com/api/v1/[endpoint]" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -d '{
    "field1": "example value",
    "field2": 123
  }'

JavaScript Example

const response = await fetch('/api/v1/[endpoint]', {
  method: '[METHOD]',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token-here'
  },
  body: JSON.stringify({
    field1: 'example value',
    field2: 123
  })
});

const data = await response.json();
console.log(data);

Python Example

import requests

url = 'https://api.yourdomain.com/api/v1/[endpoint]'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token-here'
}
data = {
    'field1': 'example value',
    'field2': 123
}

response = requests.[method](url, headers=headers, json=data)
result = response.json()
print(result)

Testing

Unit Test Example

describe('[METHOD] /api/v1/[endpoint]', () => {
  it('should return success with valid data', async () => {
    const response = await request(app)
      .[method]('/api/v1/[endpoint]')
      .send({
        field1: 'test value',
        field2: 123
      })
      .expect(200);

    expect(response.body.success).toBe(true);
    expect(response.body.data).toMatchObject({
      field1: 'test value',
      field2: 123
    });
  });

  it('should return 400 for invalid data', async () => {
    const response = await request(app)
      .[method]('/api/v1/[endpoint]')
      .send({
        field1: '', // Invalid empty string
        field2: -1  // Invalid negative number
      })
      .expect(400);

    expect(response.body.success).toBe(false);
    expect(response.body.error.code).toBe('VALIDATION_ERROR');
  });
});

Notes

• Additional implementation notes
• Performance considerations
• Security considerations
• Related endpoints

Changelog

Version	Date	Changes
1.0.0	2024-01-01	Initial implementation

---

Last Updated: [Date]
Reviewed By: [Name]
Next Review: [Date]