Sankofa/docs/infrastructure/API_DOCUMENTATION.md

Infrastructure API Documentation

Overview

The Infrastructure Documentation Dashboard uses a combination of GraphQL queries/mutations and REST API endpoints for data management.

GraphQL API

Queries

Get Network Topologies

query GetNetworkTopologies($filter: TopologyFilter) {
  networkTopologies(filter: $filter) {
    id
    region
    entity
    nodes {
      id
      type
      label
      position { x y }
    }
    edges {
      id
      source
      target
      type
    }
  }
}

Get Compliance Requirements

query GetComplianceRequirements($filter: ComplianceFilter) {
  complianceRequirements(filter: $filter) {
    country
    region
    frameworks
    status
    requirements
    lastAuditDate
  }
}

Get Deployment Milestones

query GetDeploymentMilestones($filter: MilestoneFilter) {
  deploymentMilestones(filter: $filter) {
    id
    title
    region
    entity
    priority
    startDate
    endDate
    status
    dependencies
    cost
    description
  }
}

Get Cost Estimates

query GetCostEstimates($filter: CostFilter) {
  costEstimates(filter: $filter) {
    region
    entity
    category
    monthly
    annual
    breakdown {
      compute
      storage
      network
      licenses
      personnel
    }
    currency
    lastUpdated
  }
}

Mutations

Update Network Topology

mutation UpdateNetworkTopology($id: ID!, $input: TopologyInput!) {
  updateNetworkTopology(id: $id, input: $input) {
    id
    nodes { id }
    edges { id }
  }
}

Update Compliance Requirement

mutation UpdateComplianceRequirement($country: String!, $input: ComplianceInput!) {
  updateComplianceRequirement(country: $country, input: $input) {
    country
    status
  }
}

Update Deployment Milestone

mutation UpdateDeploymentMilestone($id: ID!, $input: MilestoneInput!) {
  updateDeploymentMilestone(id: $id, input: $input) {
    id
    title
    status
  }
}

Update Cost Estimate

mutation UpdateCostEstimate($region: String!, $entity: String!, $category: String!, $input: CostInput!) {
  updateCostEstimate(region: $region, entity: $entity, category: $category, input: $input) {
    region
    entity
    monthly
    annual
  }
}

Subscriptions

Subscribe to Topology Changes

subscription SubscribeTopologyChanges($id: ID!) {
  topologyChanged(id: $id) {
    id
    nodes { id }
    edges { id }
  }
}

REST API

Data Serving

GET /api/infrastructure/data/[filename]

Serves JSON data files with caching.

Response: JSON data with cache headers

Backup/Restore

POST /api/infrastructure/backup

Creates a backup of all data files.

Response:

{
  "success": true,
  "filename": "backup-2024-01-01.json.gz",
  "timestamp": "2024-01-01T00:00:00Z",
  "files": 5
}

GET /api/infrastructure/backup

Lists all available backups.

Response:

{
  "backups": [
    {
      "filename": "backup-2024-01-01.json.gz",
      "size": 1024,
      "created": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /api/infrastructure/restore

Restores from a backup file.

Request:

{
  "filename": "backup-2024-01-01.json.gz"
}

Response:

{
  "success": true,
  "filesRestored": 5,
  "timestamp": "2024-01-01T00:00:00Z"
}

Import

POST /api/infrastructure/import

Imports data from CSV/JSON/Excel file.

Request: FormData with file and targetFile

Response:

{
  "success": true,
  "filename": "smom_countries.json",
  "records": 115
}

Data Structures

NetworkTopology

{
  id: string
  region: string
  entity: string
  nodes: TopologyNode[]
  edges: TopologyEdge[]
  lastUpdated: string
}

ComplianceRequirement

{
  country: string
  region: string
  frameworks: string[]
  status: 'Compliant' | 'Partial' | 'Pending' | 'Non-Compliant'
  requirements: string[]
  lastAuditDate?: string
  notes?: string
}

DeploymentMilestone

{
  id: string
  title: string
  region: string
  entity: string
  priority: 'Critical' | 'High' | 'Medium' | 'Low'
  startDate: string
  endDate: string
  status: 'Planned' | 'In Progress' | 'Complete' | 'Blocked'
  dependencies: string[]
  cost?: number
  description?: string
}

CostEstimate

{
  region: string
  entity: string
  category: string
  monthly: number
  annual: number
  breakdown: {
    compute?: number
    storage?: number
    network?: number
    licenses?: number
    personnel?: number
  }
  currency: string
  lastUpdated: string
}

Error Handling

All API endpoints return standard error responses:

{
  "error": "Error message",
  "message": "Detailed error description"
}

Status codes:

• 200: Success
• 400: Bad Request
• 404: Not Found
• 500: Internal Server Error

Authentication

Currently, the API does not require authentication. In production, implement:

• JWT tokens for GraphQL
• API keys for REST endpoints
• Role-based access control