263 lines
5.1 KiB
ReStructuredText
263 lines
5.1 KiB
ReStructuredText
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. |