---
template_id: "cross-platform-api-documentation"
template_name: "Cross-Platform API Documentation Template"
version: "1.0.0"
category: "persona"
personas: ["technical-documentation-architect", "cross-platform-integration-specialist"]
technologies: ["react", "typescript", "nodejs", "aspnet", "python"]
complexity: "intermediate"
estimated_time: "60-90 minutes"
dependencies: ["api-design", "technical-architecture"]
tags: ["api", "documentation", "cross-platform", "integration"]
---

# API Documentation: {{API_NAME}}

## API Overview
**API Name:** {{API_NAME}}  
**Version:** {{API_VERSION}}  
**Base URL:** {{BASE_URL}}  
**Protocol:** {{PROTOCOL}} (REST/GraphQL/gRPC)  
**Authentication:** {{AUTHENTICATION_TYPE}}  
**Last Updated:** {{LAST_UPDATED}}  

### Purpose
{{API_PURPOSE_DESCRIPTION}}

### Target Platforms
- **Frontend:** React/TypeScript applications
- **Backend:** Node.js, ASP.NET, Python services
- **Mobile:** React Native, native mobile apps
- **Third-Party:** External integrations

## Authentication

### Authentication Method
{{AUTHENTICATION_METHOD_DESCRIPTION}}

### Getting API Keys
{{API_KEY_INSTRUCTIONS}}

### Authentication Examples

#### React/TypeScript
\```typescript
// Authentication setup for React applications
const apiClient = axios.create({
  baseURL: '{{BASE_URL}}',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});
```

#### Node.js
\```javascript
// Authentication setup for Node.js services
const fetch = require('node-fetch');

const apiCall = async (endpoint, options = {}) => {
  const response = await fetch(`{{BASE_URL}}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.API_TOKEN}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
  return response.json();
};
```

#### ASP.NET
```csharp
// Authentication setup for ASP.NET services
public class ApiClient
{
    private readonly HttpClient _httpClient;
    
    public ApiClient(HttpClient httpClient, IConfiguration config)
    {
        _httpClient = httpClient;
        _httpClient.BaseAddress = new Uri(config["ApiBaseUrl"]);
        _httpClient.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Bearer", config["ApiToken"]);
    }
}
```

#### Python
```python
# Authentication setup for Python services
import requests

class ApiClient:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    
    def make_request(self, endpoint, method='GET', data=None):
        url = f"{self.base_url}{endpoint}"
        return requests.request(method, url, headers=self.headers, json=data)
```

## API Endpoints

### {{ENDPOINT_CATEGORY_1}}

#### {{ENDPOINT_1_NAME}}
**Endpoint:** `{{ENDPOINT_1_METHOD}} {{ENDPOINT_1_PATH}}`  
**Description:** {{ENDPOINT_1_DESCRIPTION}}

##### Request Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| {{PARAM_1}} | {{PARAM_1_TYPE}} | {{PARAM_1_REQUIRED}} | {{PARAM_1_DESCRIPTION}} |
| {{PARAM_2}} | {{PARAM_2_TYPE}} | {{PARAM_2_REQUIRED}} | {{PARAM_2_DESCRIPTION}} |

##### Request Body
\```json
{
  "{{REQUEST_FIELD_1}}": "{{REQUEST_FIELD_1_TYPE}}",
  "{{REQUEST_FIELD_2}}": "{{REQUEST_FIELD_2_TYPE}}"
}
```

##### Response
\```json
{
  "{{RESPONSE_FIELD_1}}": "{{RESPONSE_FIELD_1_TYPE}}",
  "{{RESPONSE_FIELD_2}}": "{{RESPONSE_FIELD_2_TYPE}}",
  "metadata": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "{{API_VERSION}}"
  }
}
```

##### Platform-Specific Examples

###### React/TypeScript
\```typescript
interface {{ENDPOINT_1_NAME}}Request {
  {{REQUEST_FIELD_1}}: {{REQUEST_FIELD_1_TS_TYPE}};
  {{REQUEST_FIELD_2}}: {{REQUEST_FIELD_2_TS_TYPE}};
}

interface {{ENDPOINT_1_NAME}}Response {
  {{RESPONSE_FIELD_1}}: {{RESPONSE_FIELD_1_TS_TYPE}};
  {{RESPONSE_FIELD_2}}: {{RESPONSE_FIELD_2_TS_TYPE}};
  metadata: {
    timestamp: string;
    version: string;
  };
}

const {{ENDPOINT_1_FUNCTION_NAME}} = async (
  data: {{ENDPOINT_1_NAME}}Request
): Promise<{{ENDPOINT_1_NAME}}Response> => {
  const response = await apiClient.{{ENDPOINT_1_METHOD_LOWER}}('{{ENDPOINT_1_PATH}}', data);
  return response.data;
};
```

###### Node.js
\```javascript
const {{ENDPOINT_1_FUNCTION_NAME}} = async (requestData) => {
  try {
    const response = await apiCall('{{ENDPOINT_1_PATH}}', {
      method: '{{ENDPOINT_1_METHOD}}',
      body: JSON.stringify(requestData)
    });
    return response;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
};
```

###### ASP.NET
```csharp
public class {{ENDPOINT_1_NAME}}Request
{
    public {{REQUEST_FIELD_1_CS_TYPE}} {{REQUEST_FIELD_1_PASCAL}} { get; set; }
    public {{REQUEST_FIELD_2_CS_TYPE}} {{REQUEST_FIELD_2_PASCAL}} { get; set; }
}

public class {{ENDPOINT_1_NAME}}Response
{
    public {{RESPONSE_FIELD_1_CS_TYPE}} {{RESPONSE_FIELD_1_PASCAL}} { get; set; }
    public {{RESPONSE_FIELD_2_CS_TYPE}} {{RESPONSE_FIELD_2_PASCAL}} { get; set; }
    public ApiMetadata Metadata { get; set; }
}

public async Task<{{ENDPOINT_1_NAME}}Response> {{ENDPOINT_1_FUNCTION_NAME}}Async({{ENDPOINT_1_NAME}}Request request)
{
    var response = await _httpClient.{{ENDPOINT_1_METHOD_PASCAL}}AsJsonAsync("{{ENDPOINT_1_PATH}}", request);
    return await response.Content.ReadFromJsonAsync<{{ENDPOINT_1_NAME}}Response>();
}
```

###### Python
```python
def {{ENDPOINT_1_FUNCTION_NAME}}(self, request_data):
    """
    {{ENDPOINT_1_DESCRIPTION}}
    
    Args:
        request_data (dict): Request payload
        
    Returns:
        dict: API response
    """
    try:
        response = self.make_request(
            '{{ENDPOINT_1_PATH}}',
            method='{{ENDPOINT_1_METHOD}}',
            data=request_data
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"API Error: {e}")
        raise
```

##### Error Responses
| Status Code | Description | Response Body |
|-------------|-------------|---------------|
| 400 | Bad Request | `{"error": "{{ERROR_400_MESSAGE}}", "code": "INVALID_REQUEST"}` |
| 401 | Unauthorized | `{"error": "{{ERROR_401_MESSAGE}}", "code": "UNAUTHORIZED"}` |
| 404 | Not Found | `{"error": "{{ERROR_404_MESSAGE}}", "code": "NOT_FOUND"}` |
| 500 | Server Error | `{"error": "{{ERROR_500_MESSAGE}}", "code": "INTERNAL_ERROR"}` |

## Data Models

### {{MODEL_1_NAME}}
\```json
{
  "{{MODEL_1_FIELD_1}}": "{{MODEL_1_FIELD_1_TYPE}}",
  "{{MODEL_1_FIELD_2}}": "{{MODEL_1_FIELD_2_TYPE}}",
  "{{MODEL_1_FIELD_3}}": {
    "{{NESTED_FIELD_1}}": "{{NESTED_FIELD_1_TYPE}}",
    "{{NESTED_FIELD_2}}": "{{NESTED_FIELD_2_TYPE}}"
  }
}
```

#### Platform-Specific Type Definitions

##### TypeScript
\```typescript
interface {{MODEL_1_NAME}} {
  {{MODEL_1_FIELD_1}}: {{MODEL_1_FIELD_1_TS_TYPE}};
  {{MODEL_1_FIELD_2}}: {{MODEL_1_FIELD_2_TS_TYPE}};
  {{MODEL_1_FIELD_3}}: {
    {{NESTED_FIELD_1}}: {{NESTED_FIELD_1_TS_TYPE}};
    {{NESTED_FIELD_2}}: {{NESTED_FIELD_2_TS_TYPE}};
  };
}
```

##### C# (ASP.NET)
```csharp
public class {{MODEL_1_NAME}}
{
    public {{MODEL_1_FIELD_1_CS_TYPE}} {{MODEL_1_FIELD_1_PASCAL}} { get; set; }
    public {{MODEL_1_FIELD_2_CS_TYPE}} {{MODEL_1_FIELD_2_PASCAL}} { get; set; }
    public {{MODEL_1_FIELD_3_NAME}} {{MODEL_1_FIELD_3_PASCAL}} { get; set; }
}

public class {{MODEL_1_FIELD_3_NAME}}
{
    public {{NESTED_FIELD_1_CS_TYPE}} {{NESTED_FIELD_1_PASCAL}} { get; set; }
    public {{NESTED_FIELD_2_CS_TYPE}} {{NESTED_FIELD_2_PASCAL}} { get; set; }
}
```

##### Python
```python
from dataclasses import dataclass
from typing import Optional

@dataclass
class {{MODEL_1_FIELD_3_NAME}}:
    {{NESTED_FIELD_1}}: {{NESTED_FIELD_1_PY_TYPE}}
    {{NESTED_FIELD_2}}: {{NESTED_FIELD_2_PY_TYPE}}

@dataclass
class {{MODEL_1_NAME}}:
    {{MODEL_1_FIELD_1}}: {{MODEL_1_FIELD_1_PY_TYPE}}
    {{MODEL_1_FIELD_2}}: {{MODEL_1_FIELD_2_PY_TYPE}}
    {{MODEL_1_FIELD_3}}: {{MODEL_1_FIELD_3_NAME}}
```

## Rate Limiting

### Rate Limits
- **Requests per minute:** {{RATE_LIMIT_PER_MINUTE}}
- **Requests per hour:** {{RATE_LIMIT_PER_HOUR}}
- **Requests per day:** {{RATE_LIMIT_PER_DAY}}

### Rate Limit Headers
```
X-RateLimit-Limit: {{RATE_LIMIT_VALUE}}
X-RateLimit-Remaining: {{REMAINING_REQUESTS}}
X-RateLimit-Reset: {{RESET_TIMESTAMP}}
```

### Handling Rate Limits

#### React/TypeScript
\```typescript
const handleRateLimit = async (apiCall: () => Promise<any>) => {
  try {
    return await apiCall();
  } catch (error) {
    if (error.response?.status === 429) {
      const resetTime = error.response.headers['x-ratelimit-reset'];
      const waitTime = new Date(resetTime * 1000) - new Date();
      await new Promise(resolve => setTimeout(resolve, waitTime));
      return await apiCall();
    }
    throw error;
  }
};
```

#### Node.js
\```javascript
const rateLimitRetry = async (apiCall, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await apiCall();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const resetTime = error.headers['x-ratelimit-reset'];
        const waitTime = (resetTime * 1000) - Date.now();
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      throw error;
    }
  }
};
```

## Error Handling

### Error Response Format
\```json
{
  "error": {
    "code": "{{ERROR_CODE}}",
    "message": "{{ERROR_MESSAGE}}",
    "details": "{{ERROR_DETAILS}}",
    "timestamp": "{{ERROR_TIMESTAMP}}"
  }
}
```

### Common Error Codes
| Code | Description | Resolution |
|------|-------------|------------|
| INVALID_REQUEST | Request validation failed | Check request parameters and format |
| UNAUTHORIZED | Authentication failed | Verify API token and permissions |
| RATE_LIMITED | Too many requests | Implement rate limiting and retry logic |
| NOT_FOUND | Resource not found | Verify resource ID and availability |
| SERVER_ERROR | Internal server error | Contact API support |

## Testing

### Test Environment
**Base URL:** {{TEST_BASE_URL}}  
**Authentication:** {{TEST_AUTH_METHOD}}

### Postman Collection
{{POSTMAN_COLLECTION_LINK}}

### Integration Testing Examples

#### React Testing Library
\```typescript
import { render, screen, waitFor } from '@testing-library/react';
import { {{ENDPOINT_1_FUNCTION_NAME}} } from './api';

jest.mock('./api');

test('should handle API response correctly', async () => {
  const mockResponse = { {{RESPONSE_FIELD_1}}: 'test' };
  ({{ENDPOINT_1_FUNCTION_NAME}} as jest.Mock).mockResolvedValue(mockResponse);
  
  render(<ComponentUsingAPI />);
  
  await waitFor(() => {
    expect(screen.getByText('test')).toBeInTheDocument();
  });
});
```

#### Node.js Testing
\```javascript
const request = require('supertest');
const app = require('../app');

describe('API Integration', () => {
  test('should return valid response', async () => {
    const response = await request(app)
      .{{ENDPOINT_1_METHOD_LOWER}}('{{ENDPOINT_1_PATH}}')
      .send({ {{REQUEST_FIELD_1}}: 'test' })
      .expect(200);
      
    expect(response.body).toHaveProperty('{{RESPONSE_FIELD_1}}');
  });
});
```

## SDK and Libraries

### Official SDKs
- **JavaScript/TypeScript:** {{JS_SDK_LINK}}
- **C#/.NET:** {{DOTNET_SDK_LINK}}
- **Python:** {{PYTHON_SDK_LINK}}

### Community Libraries
- **React Hooks:** {{REACT_HOOKS_LIBRARY}}
- **Vue.js Plugin:** {{VUE_PLUGIN_LIBRARY}}

## Changelog

### Version {{API_VERSION}}
- {{CHANGELOG_ITEM_1}}
- {{CHANGELOG_ITEM_2}}
- {{CHANGELOG_ITEM_3}}

### Migration Guide
{{MIGRATION_GUIDE_DESCRIPTION}}

## Support

### Documentation
- **API Reference:** {{API_REFERENCE_LINK}}
- **Tutorials:** {{TUTORIALS_LINK}}
- **Examples:** {{EXAMPLES_LINK}}

### Community
- **Developer Forum:** {{FORUM_LINK}}
- **Stack Overflow:** {{STACKOVERFLOW_TAG}}
- **GitHub Issues:** {{GITHUB_ISSUES_LINK}}

### Contact
- **Technical Support:** {{SUPPORT_EMAIL}}
- **Sales Inquiries:** {{SALES_EMAIL}}

---

## Template Usage Notes

### Variable Substitution Guide
Replace all `{{VARIABLE_NAME}}` placeholders with API-specific information.

### Customization Options
- Add additional endpoints as needed
- Include platform-specific optimizations
- Expand error handling sections
- Add more comprehensive examples

### Quality Validation Checklist
- [ ] All endpoints are documented with examples
- [ ] Platform-specific code examples are provided
- [ ] Error handling is comprehensive
- [ ] Authentication is clearly explained
- [ ] Rate limiting is documented
- [ ] Testing examples are included
- [ ] Data models are complete with type definitions

### Integration Points
- **BMAD Personas:** Technical Documentation Architect, Cross-Platform Integration Specialist
- **Follow-up Templates:** Integration Documentation Template
- **Quality Standards:** BMAD Method API documentation standards

---
**Template Version:** 1.0.0  
**Last Updated:** {{CURRENT_DATE}}  
**Template Owner:** BMAD Method Team