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.