Skip to content

server-api.md

Latest commit

 

History

History
266 lines (228 loc) · 4.4 KB

server-api.md

File metadata and controls

266 lines (228 loc) · 4.4 KB

Server API Reference

Complete API reference for the GraphQL proxy server's endpoints and functionality.

HTTP Endpoints

POST /graphql

GraphQL proxy endpoint

POST /graphql
Content-Type: application/json
Authorization: Bearer <token> (optional)

{
  "query": "query { posts { id title } }",
  "variables": {},
  "operationName": null
}

Response:

{
  "data": {
    "posts": [
      {
        "id": "1",
        "title": "Post Title"
      }
    ]
  }
}

Headers:

  • x-cache: "HIT" or "MISS" - cache status
  • x-cache-key: Cache key hash
  • x-mode: "GETMODE", "SETMODE", or "CRUDMODE" - current GraphQL mode
  • x-mutation: "executed" or "queued" - mutation status (for mutations)
  • x-queue-id: Queue ID (for queued mutations)

GET /health

Server health check

GET /health
Accept: application/json

Response:

{
  "ok": true,
  "port": 5001,
  "mode": "GETMODE",
  "upstream": "configured",
  "authToken": "configured",
  "cacheDir": "./data/graphql-cache",
  "queueDir": "./data/mutation-queue",
  "localDbPath": "./data/local-db.json",
  "queuedMutations": 0,
  "localData": {
    "posts": 15,
    "categories": 5,
    "tags": 8,
    "pages": 3,
    "lastUpdated": "2024-01-01T10:00:00.000Z"
  }
}

GET /local/data

Get local database contents

GET /local/data
Accept: application/json

Response:

{
  "data": {
    "posts": [],
    "categories": [],
    "tags": [],
    "authors": [],
    "pages": [],
    "lastUpdated": "2024-01-01T10:00:00.000Z"
  }
}

POST /local/sync

Sync local database from upstream GraphQL

POST /local/sync
Accept: application/json

Response:

{
  "message": "Local database synced from upstream",
  "counts": {
    "posts": 15,
    "categories": 5,
    "tags": 8,
    "pages": 3
  }
}

Error Response:

{
  "error": "UPSTREAM_GRAPHQL_ENDPOINT not configured"
}

POST /flush

Flush mutation queue

POST /flush
Accept: application/json

Response:

{
  "message": "Mutation queue flush complete",
  "flushed": 3,
  "failed": 0
}

Error Response:

{
  "error": "UPSTREAM_GRAPHQL_ENDPOINT not configured"
}

GET /queue

Get queued mutations

GET /queue
Accept: application/json

Response:

{
  "mutations": [
    {
      "id": "1640995200000-abc123def",
      "payload": {
        "query": "mutation { createPost(input: {...}) { post { id } } }",
        "variables": {},
        "operationName": null
      },
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  ]
}

GraphQL Modes

GETMODE

  • Queries: Forward to upstream, cache responses
  • Mutations: Blocked with error
  • Offline: Serve from cache

SETMODE

  • Queries: Forward to upstream, cache responses
  • Mutations: Execute if online, queue if offline, update local DB
  • Offline: Queue mutations for later execution

CRUDMODE

  • Queries: Forward to upstream, cache responses
  • Mutations: Execute if online, fail if offline, update local DB
  • Offline: Reject mutations with error

Data Types

GraphQLRequest

interface GraphQLRequest {
  query?: string;
  variables?: Record<string, any>;
  operationName?: string | null;
}

QueuedMutation

interface QueuedMutation {
  id: string;
  payload: GraphQLRequest;
  createdAt: string;
}

LocalData

interface LocalData {
  posts: any[];
  categories: any[];
  tags: any[];
  authors: any[];
  pages: any[];
  site?: any;
  menu?: any[];
  lastUpdated?: string;
}

Error Handling

GraphQL Errors

{
  "errors": [
    {
      "message": "Upstream GraphQL is unavailable and cache miss occurred for this query.",
      "extensions": {
        "code": "OFFLINE_CACHE_MISS",
        "cacheKey": "abc123..."
      }
    }
  ]
}

Mutation Blocking

{
  "errors": [
    {
      "message": "Mutations are disabled in GETMODE",
      "extensions": {
        "code": "MUTATION_BLOCKED"
      }
    }
  ]
}

CORS Configuration

All endpoints support CORS with configurable origin:

  • Default: * (allow all)
  • Configurable via CORS_ORIGIN environment variable

Preflight Response:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, authorization
Access-Control-Allow-Methods: GET, POST, OPTIONS