DeBros/network
4
0
Fork 0
mirror of https://github.com/DeBrosOfficial/network.git synced 2026-01-30 03:43:04 +00:00
Code Issues Packages Projects Releases Wiki Activity
network/docs/GATEWAY_API.md
anonpenguin23 b0bc0a232e Refactored the whole codebase to be much cleaner
2026-01-20 10:03:55 +02:00

11 KiB
Raw Blame History

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:

curl -H "Authorization: Bearer your-api-key-here" \
     https://api.orama.network/v1/status

Or in the X-API-Key header:

curl -H "X-API-Key: your-api-key-here" \
     https://api.orama.network/v1/status

Using JWT Tokens

curl -H "Authorization: Bearer your-jwt-token-here" \
     https://api.orama.network/v1/status

Base Endpoints

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2024-01-20T10:30:00Z"
}

Status

GET /v1/status

Response:

{
  "version": "0.80.0",
  "uptime": "24h30m15s",
  "services": {
    "rqlite": "healthy",
    "ipfs": "healthy",
    "olric": "healthy"
  }
}

Version

GET /v1/version

Response:

{
  "version": "0.80.0",
  "commit": "abc123...",
  "built": "2024-01-20T00:00:00Z"
}

Authentication API

Get Challenge (Wallet Auth)

Generate a nonce for wallet signature.

POST /v1/auth/challenge
Content-Type: application/json

{
  "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "purpose": "login",
  "namespace": "default"
}

Response:

{
  "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.

POST /v1/auth/verify
Content-Type: application/json

{
  "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "signature": "0x...",
  "nonce": "a1b2c3d4e5f6...",
  "namespace": "default"
}

Response:

{
  "jwt_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "refresh_abc123...",
  "api_key": "api_xyz789...",
  "expires_in": 900,
  "namespace": "default"
}

Refresh Token

Refresh an expired JWT token.

POST /v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "refresh_abc123..."
}

Response:

{
  "jwt_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 900
}

Logout

Revoke refresh tokens.

POST /v1/auth/logout
Authorization: Bearer your-jwt-token

{
  "all": false
}

Response:

{
  "message": "logged out successfully"
}

Whoami

Get current authentication info.

GET /v1/auth/whoami
Authorization: Bearer your-api-key

Response:

{
  "authenticated": true,
  "method": "api_key",
  "api_key": "api_xyz789...",
  "namespace": "default"
}

Storage API (IPFS)

Upload File

POST /v1/storage/upload
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

file: <binary data>

Or with JSON:

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:

{
  "cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
  "size": 1024,
  "filename": "document.pdf"
}

Get File

GET /v1/storage/get/:cid
Authorization: Bearer your-api-key

Response: Binary file data or JSON (if Accept: application/json)

Pin File

POST /v1/storage/pin
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
  "replication_factor": 3
}

Response:

{
  "cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
  "status": "pinned"
}

Unpin File

DELETE /v1/storage/unpin/:cid
Authorization: Bearer your-api-key

Response:

{
  "message": "unpinned successfully"
}

Get Pin Status

GET /v1/storage/status/:cid
Authorization: Bearer your-api-key

Response:

{
  "cid": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
  "status": "pinned",
  "replicas": 3,
  "peers": ["12D3KooW...", "12D3KooW..."]
}

Cache API (Olric)

Set Value

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:

{
  "message": "value set successfully"
}

Get Value

GET /v1/cache/get?key=user:123
Authorization: Bearer your-api-key

Response:

{
  "key": "user:123",
  "value": {"name": "Alice", "email": "alice@example.com"}
}

Get Multiple Values

POST /v1/cache/mget
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "keys": ["user:1", "user:2", "user:3"]
}

Response:

{
  "results": {
    "user:1": {"name": "Alice"},
    "user:2": {"name": "Bob"},
    "user:3": null
  }
}

Delete Value

DELETE /v1/cache/delete?key=user:123
Authorization: Bearer your-api-key

Response:

{
  "message": "deleted successfully"
}

Scan Keys

GET /v1/cache/scan?pattern=user:*&limit=100
Authorization: Bearer your-api-key

Response:

{
  "keys": ["user:1", "user:2", "user:3"],
  "count": 3
}

Database API (RQLite)

Execute SQL

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:

{
  "last_insert_id": 123,
  "rows_affected": 1
}

Query SQL

POST /v1/rqlite/query
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "sql": "SELECT * FROM users WHERE id = ?",
  "args": [123]
}

Response:

{
  "columns": ["id", "name", "email"],
  "rows": [
    [123, "Alice", "alice@example.com"]
  ]
}

Get Schema

GET /v1/rqlite/schema
Authorization: Bearer your-api-key

Response:

{
  "tables": [
    {
      "name": "users",
      "schema": "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)"
    }
  ]
}

Pub/Sub API

Publish Message

POST /v1/pubsub/publish
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "topic": "chat",
  "data": "SGVsbG8sIFdvcmxkIQ==",
  "namespace": "default"
}

Response:

{
  "message": "published successfully"
}

List Topics

GET /v1/pubsub/topics
Authorization: Bearer your-api-key

Response:

{
  "topics": ["chat", "notifications", "events"]
}

Subscribe (WebSocket)

GET /v1/pubsub/ws?topic=chat
Authorization: Bearer your-api-key
Upgrade: websocket

WebSocket Messages:

Incoming (from server):

{
  "type": "message",
  "topic": "chat",
  "data": "SGVsbG8sIFdvcmxkIQ==",
  "timestamp": "2024-01-20T10:30:00Z"
}

Outgoing (to server):

{
  "type": "publish",
  "topic": "chat",
  "data": "SGVsbG8sIFdvcmxkIQ=="
}

Presence

GET /v1/pubsub/presence?topic=chat
Authorization: Bearer your-api-key

Response:

{
  "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

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:

{
  "id": "fn_abc123",
  "name": "hello-world",
  "namespace": "default",
  "wasm_cid": "QmXxx...",
  "version": 1,
  "created_at": "2024-01-20T10:30:00Z"
}

Invoke Function

POST /v1/functions/hello-world/invoke
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "name": "Alice"
}

Response:

{
  "result": "Hello, Alice!",
  "execution_time_ms": 15,
  "memory_used_mb": 2.5
}

List Functions

GET /v1/functions?namespace=default
Authorization: Bearer your-api-key

Response:

{
  "functions": [
    {
      "name": "hello-world",
      "description": "Hello world function",
      "version": 1,
      "created_at": "2024-01-20T10:30:00Z"
    }
  ]
}

Delete Function

DELETE /v1/functions/hello-world?namespace=default
Authorization: Bearer your-api-key

Response:

{
  "message": "function deleted successfully"
}

Get Function Logs

GET /v1/functions/hello-world/logs?limit=100
Authorization: Bearer your-api-key

Response:

{
  "logs": [
    {
      "timestamp": "2024-01-20T10:30:00Z",
      "level": "info",
      "message": "Function invoked",
      "invocation_id": "inv_xyz789"
    }
  ]
}

Error Responses

All errors follow a consistent format:

{
  "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:

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "rate limit exceeded",
  "details": {
    "limit": 100,
    "retry_after": 60
  }
}

Pagination

List endpoints support pagination:

GET /v1/functions?limit=10&offset=20

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 100,
    "limit": 10,
    "offset": 20,
    "has_more": true
  }
}

Webhooks (Future)

Coming soon: webhook support for event notifications.

Support