mirror of
https://github.com/DeBrosOfficial/network.git
synced 2026-01-30 12:43:04 +00:00
735 lines
11 KiB
Markdown
735 lines
11 KiB
Markdown
# Gateway API Documentation
|
|
|
|
## Overview
|
|
|
|
The Orama Network Gateway provides a unified HTTP/HTTPS API for all network services. It handles authentication, routing, and service coordination.
|
|
|
|
**Base URL:** `https://api.orama.network` (production) or `http://localhost:6001` (development)
|
|
|
|
## Authentication
|
|
|
|
All API requests (except `/health` and `/v1/auth/*`) require authentication.
|
|
|
|
### Authentication Methods
|
|
|
|
1. **API Key** (Recommended for server-to-server)
|
|
2. **JWT Token** (Recommended for user sessions)
|
|
3. **Wallet Signature** (For blockchain integration)
|
|
|
|
### Using API Keys
|
|
|
|
Include your API key in the `Authorization` header:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer your-api-key-here" \
|
|
https://api.orama.network/v1/status
|
|
```
|
|
|
|
Or in the `X-API-Key` header:
|
|
|
|
```bash
|
|
curl -H "X-API-Key: your-api-key-here" \
|
|
https://api.orama.network/v1/status
|
|
```
|
|
|
|
### Using JWT Tokens
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer your-jwt-token-here" \
|
|
https://api.orama.network/v1/status
|
|
```
|
|
|
|
## Base Endpoints
|
|
|
|
### Health Check
|
|
|
|
```http
|
|
GET /health
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"timestamp": "2024-01-20T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
### Status
|
|
|
|
```http
|
|
GET /v1/status
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"version": "0.80.0",
|
|
"uptime": "24h30m15s",
|
|
"services": {
|
|
"rqlite": "healthy",
|
|
"ipfs": "healthy",
|
|
"olric": "healthy"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Version
|
|
|
|
```http
|
|
GET /v1/version
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"version": "0.80.0",
|
|
"commit": "abc123...",
|
|
"built": "2024-01-20T00:00:00Z"
|
|
}
|
|
```
|
|
|
|
## Authentication API
|
|
|
|
### Get Challenge (Wallet Auth)
|
|
|
|
Generate a nonce for wallet signature.
|
|
|
|
```http
|
|
POST /v1/auth/challenge
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
|
|
"purpose": "login",
|
|
"namespace": "default"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
|
|
"namespace": "default",
|
|
"nonce": "a1b2c3d4e5f6...",
|
|
"purpose": "login",
|
|
"expires_at": "2024-01-20T10:35:00Z"
|
|
}
|
|
```
|
|
|
|
### Verify Signature
|
|
|
|
Verify wallet signature and issue JWT + API key.
|
|
|
|
```http
|
|
POST /v1/auth/verify
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
|
|
"signature": "0x...",
|
|
"nonce": "a1b2c3d4e5f6...",
|
|
"namespace": "default"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"jwt_token": "eyJhbGciOiJIUzI1NiIs...",
|
|
"refresh_token": "refresh_abc123...",
|
|
"api_key": "api_xyz789...",
|
|
"expires_in": 900,
|
|
"namespace": "default"
|
|
}
|
|
```
|
|
|
|
### Refresh Token
|
|
|
|
Refresh an expired JWT token.
|
|
|
|
```http
|
|
POST /v1/auth/refresh
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"refresh_token": "refresh_abc123..."
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"jwt_token": "eyJhbGciOiJIUzI1NiIs...",
|
|
"expires_in": 900
|
|
}
|
|
```
|
|
|
|
### Logout
|
|
|
|
Revoke refresh tokens.
|
|
|
|
```http
|
|
POST /v1/auth/logout
|
|
Authorization: Bearer your-jwt-token
|
|
|
|
{
|
|
"all": false
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"message": "logged out successfully"
|
|
}
|
|
```
|
|
|
|
### Whoami
|
|
|
|
Get current authentication info.
|
|
|
|
```http
|
|
GET /v1/auth/whoami
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"authenticated": true,
|
|
"method": "api_key",
|
|
"api_key": "api_xyz789...",
|
|
"namespace": "default"
|
|
}
|
|
```
|
|
|
|
## Storage API (IPFS)
|
|
|
|
### Upload File
|
|
|
|
```http
|
|
POST /v1/storage/upload
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: multipart/form-data
|
|
|
|
file: <binary data>
|
|
```
|
|
|
|
Or with JSON:
|
|
|
|
```http
|
|
POST /v1/storage/upload
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"data": "base64-encoded-data",
|
|
"filename": "document.pdf",
|
|
"pin": true,
|
|
"encrypt": false
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
|
|
"size": 1024,
|
|
"filename": "document.pdf"
|
|
}
|
|
```
|
|
|
|
### Get File
|
|
|
|
```http
|
|
GET /v1/storage/get/:cid
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:** Binary file data or JSON (if `Accept: application/json`)
|
|
|
|
### Pin File
|
|
|
|
```http
|
|
POST /v1/storage/pin
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
|
|
"replication_factor": 3
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
|
|
"status": "pinned"
|
|
}
|
|
```
|
|
|
|
### Unpin File
|
|
|
|
```http
|
|
DELETE /v1/storage/unpin/:cid
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"message": "unpinned successfully"
|
|
}
|
|
```
|
|
|
|
### Get Pin Status
|
|
|
|
```http
|
|
GET /v1/storage/status/:cid
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
|
|
"status": "pinned",
|
|
"replicas": 3,
|
|
"peers": ["12D3KooW...", "12D3KooW..."]
|
|
}
|
|
```
|
|
|
|
## Cache API (Olric)
|
|
|
|
### Set Value
|
|
|
|
```http
|
|
PUT /v1/cache/put
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"key": "user:123",
|
|
"value": {"name": "Alice", "email": "alice@example.com"},
|
|
"ttl": 300
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"message": "value set successfully"
|
|
}
|
|
```
|
|
|
|
### Get Value
|
|
|
|
```http
|
|
GET /v1/cache/get?key=user:123
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"key": "user:123",
|
|
"value": {"name": "Alice", "email": "alice@example.com"}
|
|
}
|
|
```
|
|
|
|
### Get Multiple Values
|
|
|
|
```http
|
|
POST /v1/cache/mget
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"keys": ["user:1", "user:2", "user:3"]
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"results": {
|
|
"user:1": {"name": "Alice"},
|
|
"user:2": {"name": "Bob"},
|
|
"user:3": null
|
|
}
|
|
}
|
|
```
|
|
|
|
### Delete Value
|
|
|
|
```http
|
|
DELETE /v1/cache/delete?key=user:123
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"message": "deleted successfully"
|
|
}
|
|
```
|
|
|
|
### Scan Keys
|
|
|
|
```http
|
|
GET /v1/cache/scan?pattern=user:*&limit=100
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"keys": ["user:1", "user:2", "user:3"],
|
|
"count": 3
|
|
}
|
|
```
|
|
|
|
## Database API (RQLite)
|
|
|
|
### Execute SQL
|
|
|
|
```http
|
|
POST /v1/rqlite/exec
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"sql": "INSERT INTO users (name, email) VALUES (?, ?)",
|
|
"args": ["Alice", "alice@example.com"]
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"last_insert_id": 123,
|
|
"rows_affected": 1
|
|
}
|
|
```
|
|
|
|
### Query SQL
|
|
|
|
```http
|
|
POST /v1/rqlite/query
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"sql": "SELECT * FROM users WHERE id = ?",
|
|
"args": [123]
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"columns": ["id", "name", "email"],
|
|
"rows": [
|
|
[123, "Alice", "alice@example.com"]
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get Schema
|
|
|
|
```http
|
|
GET /v1/rqlite/schema
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"tables": [
|
|
{
|
|
"name": "users",
|
|
"schema": "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Pub/Sub API
|
|
|
|
### Publish Message
|
|
|
|
```http
|
|
POST /v1/pubsub/publish
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"topic": "chat",
|
|
"data": "SGVsbG8sIFdvcmxkIQ==",
|
|
"namespace": "default"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"message": "published successfully"
|
|
}
|
|
```
|
|
|
|
### List Topics
|
|
|
|
```http
|
|
GET /v1/pubsub/topics
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"topics": ["chat", "notifications", "events"]
|
|
}
|
|
```
|
|
|
|
### Subscribe (WebSocket)
|
|
|
|
```http
|
|
GET /v1/pubsub/ws?topic=chat
|
|
Authorization: Bearer your-api-key
|
|
Upgrade: websocket
|
|
```
|
|
|
|
**WebSocket Messages:**
|
|
|
|
Incoming (from server):
|
|
```json
|
|
{
|
|
"type": "message",
|
|
"topic": "chat",
|
|
"data": "SGVsbG8sIFdvcmxkIQ==",
|
|
"timestamp": "2024-01-20T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
Outgoing (to server):
|
|
```json
|
|
{
|
|
"type": "publish",
|
|
"topic": "chat",
|
|
"data": "SGVsbG8sIFdvcmxkIQ=="
|
|
}
|
|
```
|
|
|
|
### Presence
|
|
|
|
```http
|
|
GET /v1/pubsub/presence?topic=chat
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"topic": "chat",
|
|
"members": [
|
|
{"id": "user-123", "joined_at": "2024-01-20T10:00:00Z"},
|
|
{"id": "user-456", "joined_at": "2024-01-20T10:15:00Z"}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Serverless API (WASM)
|
|
|
|
### Deploy Function
|
|
|
|
```http
|
|
POST /v1/functions
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: multipart/form-data
|
|
|
|
name: hello-world
|
|
namespace: default
|
|
description: Hello world function
|
|
wasm: <binary WASM file>
|
|
memory_limit: 64
|
|
timeout: 30
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": "fn_abc123",
|
|
"name": "hello-world",
|
|
"namespace": "default",
|
|
"wasm_cid": "QmXxx...",
|
|
"version": 1,
|
|
"created_at": "2024-01-20T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
### Invoke Function
|
|
|
|
```http
|
|
POST /v1/functions/hello-world/invoke
|
|
Authorization: Bearer your-api-key
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"name": "Alice"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"result": "Hello, Alice!",
|
|
"execution_time_ms": 15,
|
|
"memory_used_mb": 2.5
|
|
}
|
|
```
|
|
|
|
### List Functions
|
|
|
|
```http
|
|
GET /v1/functions?namespace=default
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"functions": [
|
|
{
|
|
"name": "hello-world",
|
|
"description": "Hello world function",
|
|
"version": 1,
|
|
"created_at": "2024-01-20T10:30:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Delete Function
|
|
|
|
```http
|
|
DELETE /v1/functions/hello-world?namespace=default
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"message": "function deleted successfully"
|
|
}
|
|
```
|
|
|
|
### Get Function Logs
|
|
|
|
```http
|
|
GET /v1/functions/hello-world/logs?limit=100
|
|
Authorization: Bearer your-api-key
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"logs": [
|
|
{
|
|
"timestamp": "2024-01-20T10:30:00Z",
|
|
"level": "info",
|
|
"message": "Function invoked",
|
|
"invocation_id": "inv_xyz789"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Error Responses
|
|
|
|
All errors follow a consistent format:
|
|
|
|
```json
|
|
{
|
|
"code": "NOT_FOUND",
|
|
"message": "user with ID '123' not found",
|
|
"details": {
|
|
"resource": "user",
|
|
"id": "123"
|
|
},
|
|
"trace_id": "trace-abc123"
|
|
}
|
|
```
|
|
|
|
### Common Error Codes
|
|
|
|
| Code | HTTP Status | Description |
|
|
|------|-------------|-------------|
|
|
| `VALIDATION_ERROR` | 400 | Invalid input |
|
|
| `UNAUTHORIZED` | 401 | Authentication required |
|
|
| `FORBIDDEN` | 403 | Permission denied |
|
|
| `NOT_FOUND` | 404 | Resource not found |
|
|
| `CONFLICT` | 409 | Resource already exists |
|
|
| `TIMEOUT` | 408 | Operation timeout |
|
|
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
|
|
| `SERVICE_UNAVAILABLE` | 503 | Service unavailable |
|
|
| `INTERNAL` | 500 | Internal server error |
|
|
|
|
## Rate Limiting
|
|
|
|
The API implements rate limiting per API key:
|
|
|
|
- **Default:** 100 requests per minute
|
|
- **Burst:** 200 requests
|
|
|
|
Rate limit headers:
|
|
```
|
|
X-RateLimit-Limit: 100
|
|
X-RateLimit-Remaining: 95
|
|
X-RateLimit-Reset: 1611144000
|
|
```
|
|
|
|
When rate limited:
|
|
```json
|
|
{
|
|
"code": "RATE_LIMIT_EXCEEDED",
|
|
"message": "rate limit exceeded",
|
|
"details": {
|
|
"limit": 100,
|
|
"retry_after": 60
|
|
}
|
|
}
|
|
```
|
|
|
|
## Pagination
|
|
|
|
List endpoints support pagination:
|
|
|
|
```http
|
|
GET /v1/functions?limit=10&offset=20
|
|
```
|
|
|
|
Response includes pagination metadata:
|
|
```json
|
|
{
|
|
"data": [...],
|
|
"pagination": {
|
|
"total": 100,
|
|
"limit": 10,
|
|
"offset": 20,
|
|
"has_more": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## Webhooks (Future)
|
|
|
|
Coming soon: webhook support for event notifications.
|
|
|
|
## Support
|
|
|
|
- API Issues: https://github.com/DeBrosOfficial/network/issues
|
|
- OpenAPI Spec: `openapi/gateway.yaml`
|
|
- SDK Documentation: `docs/CLIENT_SDK.md`
|