Phase 2 build initial

hcfs-python/docs/api/reference.rst

@@ -0,0 +1,263 @@
+API Reference
+=============
+
+Complete OpenAPI/Swagger documentation for the HCFS REST API.
+
+Interactive Documentation
+--------------------------
+
+The HCFS API provides interactive documentation through:
+
+* **Swagger UI**: Available at ``/docs`` endpoint
+* **ReDoc**: Available at ``/redoc`` endpoint  
+* **OpenAPI Spec**: Available at ``/openapi.json`` endpoint
+
+Base URL
+--------
+
+Production API:
+  https://api.hcfs.dev/v1
+
+Staging API:
+  https://staging-api.hcfs.dev/v1
+
+Local Development:
+  http://localhost:8000
+
+Authentication
+--------------
+
+The API supports two authentication methods:
+
+API Key Authentication
+~~~~~~~~~~~~~~~~~~~~~~
+
+Include your API key in the request header:
+
+.. code-block:: http
+
+   X-API-Key: your-api-key-here
+
+JWT Token Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Include a JWT bearer token in the authorization header:
+
+.. code-block:: http
+
+   Authorization: Bearer your-jwt-token-here
+
+Rate Limiting
+-------------
+
+All API endpoints are rate limited to ensure fair usage:
+
+* **Default Limit**: 100 requests per minute
+* **Burst Limit**: 20 requests per burst
+* **Rate Limit Headers**: Included in all responses
+
+Rate limit headers:
+
+* ``X-RateLimit-Limit``: Maximum requests per window
+* ``X-RateLimit-Remaining``: Remaining requests in current window  
+* ``X-RateLimit-Reset``: Unix timestamp when window resets
+* ``Retry-After``: Seconds to wait when rate limited
+
+Complete API Specification
+---------------------------
+
+.. openapi:: ../../openapi.yaml
+   :format: swagger
+   :examples:
+
+Error Handling
+--------------
+
+The API uses standard HTTP status codes and returns consistent error responses:
+
+Success Codes
+~~~~~~~~~~~~~
+
+* ``200 OK``: Request successful
+* ``201 Created``: Resource created successfully
+
+Client Error Codes
+~~~~~~~~~~~~~~~~~~~
+
+* ``400 Bad Request``: Invalid request data
+* ``401 Unauthorized``: Authentication required
+* ``403 Forbidden``: Insufficient permissions
+* ``404 Not Found``: Resource not found
+* ``422 Unprocessable Entity``: Validation error
+* ``429 Too Many Requests``: Rate limit exceeded
+
+Server Error Codes
+~~~~~~~~~~~~~~~~~~~
+
+* ``500 Internal Server Error``: Server error
+* ``502 Bad Gateway``: Upstream server error
+* ``503 Service Unavailable``: Service temporarily unavailable
+
+Error Response Format
+~~~~~~~~~~~~~~~~~~~~~
+
+All error responses follow this structure:
+
+.. code-block:: json
+
+   {
+     "success": false,
+     "error": "Brief error description",
+     "error_details": [
+       {
+         "field": "field_name",
+         "message": "Detailed error message",
+         "code": "error_code"
+       }
+     ],
+     "timestamp": "2024-01-15T10:30:00Z",
+     "request_id": "req_123456789",
+     "api_version": "v1"
+   }
+
+Response Format
+---------------
+
+All API responses follow a consistent structure:
+
+Success Response
+~~~~~~~~~~~~~~~~
+
+.. code-block:: json
+
+   {
+     "success": true,
+     "data": { /* response data */ },
+     "timestamp": "2024-01-15T10:30:00Z",
+     "api_version": "v1"
+   }
+
+List Response with Pagination
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: json
+
+   {
+     "success": true,
+     "data": [ /* array of items */ ],
+     "pagination": {
+       "page": 1,
+       "page_size": 20,
+       "total_items": 150,
+       "total_pages": 8,
+       "has_next": true,
+       "has_previous": false
+     },
+     "timestamp": "2024-01-15T10:30:00Z",
+     "api_version": "v1"
+   }
+
+WebSocket API
+-------------
+
+Real-time updates are available through WebSocket connections.
+
+Connection
+~~~~~~~~~~
+
+Connect to: ``wss://api.hcfs.dev/ws`` (or ``ws://localhost:8000/ws`` for local)
+
+Authentication
+~~~~~~~~~~~~~~
+
+Include authentication in connection headers:
+
+.. code-block:: javascript
+
+   const ws = new WebSocket('wss://api.hcfs.dev/ws', {
+     headers: {
+       'X-API-Key': 'your-api-key'
+     }
+   });
+
+Subscription
+~~~~~~~~~~~~
+
+Subscribe to events by sending a subscription message:
+
+.. code-block:: json
+
+   {
+     "type": "subscribe",
+     "data": {
+       "path_prefix": "/docs",
+       "event_types": ["created", "updated", "deleted"],
+       "filters": {}
+     }
+   }
+
+Event Messages
+~~~~~~~~~~~~~~
+
+You'll receive event messages in this format:
+
+.. code-block:: json
+
+   {
+     "type": "context_created",
+     "data": {
+       "id": 123,
+       "path": "/docs/new-guide",
+       "content": "...",
+       /* full context object */
+     },
+     "timestamp": "2024-01-15T10:30:00Z"
+   }
+
+Monitoring
+----------
+
+Health Check
+~~~~~~~~~~~~
+
+Monitor API health:
+
+.. code-block:: http
+
+   GET /health
+
+Returns component health status and response times.
+
+Metrics
+~~~~~~~
+
+Prometheus metrics available at:
+
+.. code-block:: http
+
+   GET /metrics
+
+Includes request counts, response times, and system metrics.
+
+SDK Integration
+---------------
+
+For easier API integration, use the official Python SDK:
+
+.. code-block:: bash
+
+   pip install hcfs-sdk
+
+.. code-block:: python
+
+   from hcfs.sdk import HCFSClient
+
+   client = HCFSClient(
+       base_url="https://api.hcfs.dev/v1",
+       api_key="your-api-key"
+   )
+
+   # The SDK handles authentication, retries, and error handling automatically
+   contexts = client.list_contexts()
+
+See the :doc:`../sdk/overview` for complete SDK documentation.