Nodes API Reference

Manage cloud infrastructure, servers, and virtual machines through the Nodes API. This API provides comprehensive infrastructure management capabilities across multiple cloud providers.

Endpoints Overview

Method	Endpoint	Description
GET	`/api/nodes`	List all configured nodes
POST	`/api/nodes/add`	Add a new node
PUT	`/api/nodes/edit`	Edit an existing node
GET	`/api/nodes/{nodeName}`	Get specific node details
POST	`/api/nodes/test-connection`	Test SSH connection
POST	`/api/nodes/verify`	Verify node connection
POST	`/api/nodes/execute`	Execute command on node
POST	`/api/nodes/state/{action}`	Control application state

SSH Key Management

List SSH Keys

GET /api/nodes/ssh-keys

Response:

{
  "success": true,
  "keys": [
    {
      "id": "key-123456",
      "name": "my-ssh-key",
      "path": "/uploads/keys/my-ssh-key",
      "publicKey": "ssh-rsa AAAA...",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Add SSH Key

POST /api/nodes/ssh-keys

Request Body (multipart/form-data):

name (string, required): Key name
privateKey (file, optional): Private key file
privateKeyContent (string, optional): Private key content

Response:

{
  "success": true,
  "key": {
    "id": "key-123456",
    "name": "my-ssh-key",
    "path": "/uploads/keys/my-ssh-key",
    "publicKey": "ssh-rsa AAAA...",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "message": "SSH key added successfully"
}

Node Management

List All Nodes

GET /api/nodes

Response:

{
  "all": {
    "hosts": {
      "test-anvil-01": {
        "name": "test-anvil-01",
        "host": "3.84.243.191",
        "user": "ubuntu",
        "port": "22",
        "provider": "AWS",
        "location": "us-east-1",
        "instance_type": "t2.micro",
        "infrastructure": {
          "instance_id": "i-1234567890abcdef0",
          "operated_by": "o1",
          "provisioned_at": "2024-01-15T10:30:00Z"
        }
      }
    },
    "children": {
      "anvil": {
        "type": "application",
        "hosts": {
          "test-anvil-01": {
            "vars": {
              "anvil_port": 8545,
              "accounts": 10
            },
            "deployment_mode": "binary",
            "last_deployment": "2024-01-15T10:30:00Z"
          }
        }
      }
    }
  }
}

Add a New Node

POST /api/nodes/add

Request Body (multipart/form-data):

name (string, required): Unique node name
host (string, required): Hostname or IP address
user (string, required): SSH username
port (string, optional): SSH port (default: 22)
password (string, optional): SSH password
ansible_ssh_private_key_file (file, optional): SSH private key
provider (string, optional): Cloud provider (AWS, Azure, GCP, DigitalOcean)
location (string, optional): Region/location
instance_type (string, optional): Instance type/size

Response:

{
  "success": true,
  "message": "Node added successfully"
}

Get Node Details

GET /api/nodes/{nodeName}

Parameters:

nodeName (path): Name of the node

Response:

{
  "success": true,
  "node": {
    "name": "test-anvil-01",
    "host": "3.84.243.191",
    "user": "ubuntu",
    "port": "22",
    "provider": "AWS",
    "location": "us-east-1",
    "instance_type": "t2.micro",
    "infrastructure": {
      "instance_id": "i-1234567890abcdef0",
      "operated_by": "o1",
      "provisioned_at": "2024-01-15T10:30:00Z"
    },
    "metadata": {
      "os": "Ubuntu 22.04.3 LTS",
      "architecture": "x86_64",
      "kernel": "5.15.0-91-generic",
      "cpu_cores": 2,
      "memory_mb": 8192,
      "disk_gb": 100,
      "collected_at": "2024-01-15T10:30:00Z"
    },
    "deployed_apps": [
      {
        "name": "Anvil",
        "version": "1.0.0",
        "deployment_mode": "binary",
        "deployed_at": "2024-01-15T10:30:00Z",
        "status": "running"
      }
    ]
  }
}

Cloud Instance Management

Launch Cloud Instance

POST /api/nodes/launch-instance

Request Body (JSON):

{
  "credentialName": "production-aws",
  "provider": "AWS",
  "region": "us-east-1",
  "instanceType": "t2.micro",
  "name": "web-server-01",
  "sshKeyName": "my-key-pair",
  "createSecurityGroup": true,
  "volumeSize": 50,
  "tags": {
    "Environment": "production",
    "Project": "web-app"
  }
}

Response:

{
  "success": true,
  "instance": {
    "instanceId": "i-1234567890abcdef0",
    "name": "web-server-01",
    "publicIp": "3.84.243.191",
    "privateIp": "10.0.1.100",
    "status": "running",
    "provider": "AWS",
    "region": "us-east-1",
    "instanceType": "t2.micro",
    "launchTime": "2024-01-15T10:30:00Z"
  },
  "message": "Instance launched successfully"
}

Terminate Instance

POST /api/nodes/terminate-instance

Request Body (JSON):

{
  "nodeName": "web-server-01"
}

Response:

{
  "success": true,
  "message": "Instance terminated successfully"
}

Restart Instance

POST /api/nodes/restart-instance

Request Body (JSON):

{
  "nodeName": "web-server-01"
}

Response:

{
  "success": true,
  "message": "Instance restarted successfully"
}

Connection Management

Test Connection

POST /api/nodes/test-connection

Request Body (multipart/form-data):

host (string, required): Hostname or IP
user (string, required): SSH username
port (string, optional): SSH port
password (string, optional): SSH password
ansible_ssh_private_key_file (file, optional): SSH private key

Response:

{
  "message": "Connection successful",
  "success": true
}

Verify Node

POST /api/nodes/verify

Request Body (JSON):

{
  "name": "test-anvil-01"
}

Response:

{
  "success": true,
  "message": "Node verified successfully"
}

Execute Command

POST /api/nodes/execute

Request Body (JSON):

{
  "node": "test-anvil-01",
  "application": "Anvil",
  "command": "docker ps",
  "setup_mode": "docker",
  "args": {
    "filter": "name=anvil"
  }
}

Response:

{
  "success": true,
  "error": null,
  "output": "CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS   PORTS     NAMES",
  "raw": "Full command output..."
}

Resource Management

Add Firewall Rule

POST /api/nodes/{nodeName}/resources/firewall

Request Body (JSON):

{
  "protocol": "tcp",
  "port": "80",
  "source": "0.0.0.0/0",
  "description": "Allow HTTP traffic"
}

Response:

{
  "success": true,
  "rule": {
    "id": "rule-123456",
    "protocol": "tcp",
    "port": "80",
    "source": "0.0.0.0/0",
    "description": "Allow HTTP traffic",
    "createdBy": "o1"
  }
}

Create Volume

POST /api/nodes/{nodeName}/resources/volumes

Request Body (JSON):

{
  "sizeGb": 100,
  "volumeType": "gp3",
  "device": "/dev/sdf",
  "description": "Application data volume"
}

Response:

{
  "success": true,
  "volume": {
    "id": "vol-12345678",
    "sizeGb": 100,
    "volumeType": "gp3",
    "device": "/dev/sdf",
    "description": "Application data volume",
    "attachedAt": "2024-01-15T10:30:00Z"
  }
}

Discovery & Exploration

Discover Cloud Instances

POST /api/nodes/discover-instances

Request Body (multipart/form-data):

credentials (string, required): JSON string with provider credentials
saveCredentials (string, optional): Whether to save credentials
credentialName (string, optional): Name for saved credentials

Response:

{
  "instances": [
    {
      "instanceId": "i-1234567890abcdef0",
      "name": "test-anvil-01",
      "publicIp": "3.84.243.191",
      "privateIp": "10.0.1.100",
      "status": "running",
      "provider": "AWS",
      "region": "us-east-1",
      "instanceType": "t2.micro"
    }
  ],
  "credentialsSaved": true
}

Get Instance Types

GET /api/nodes/instance-types/{provider}/{region}

Parameters:

provider (path): Cloud provider (AWS, Azure, GCP, DigitalOcean)
region (path): Cloud region

Response:

{
  "success": true,
  "instanceTypes": [
    {
      "name": "t2.micro",
      "vcpus": 1,
      "memory": 1024,
      "price": 0.0116
    },
    {
      "name": "t2.small",
      "vcpus": 1,
      "memory": 2048,
      "price": 0.023
    }
  ]
}

Error Responses

Common error responses for Nodes API:

{
  "success": false,
  "error": "Node not found",
  "details": {
    "nodeName": "non-existent-node"
  }
}

{
  "success": false,
  "error": "SSH connection failed",
  "details": {
    "host": "192.168.1.100",
    "user": "ubuntu",
    "output": "Connection timeout"
  }
}

Best Practices

Security

Use SSH keys instead of passwords whenever possible
Limit SSH access to specific IP ranges
Regularly rotate SSH keys and credentials
Monitor failed connection attempts

Performance

Use connection pooling for frequent operations
Cache instance type information when possible
Implement proper error handling and retry logic
Monitor resource usage and API limits

Automation

Use infrastructure-as-code approaches
Implement proper state management
Set up monitoring and alerting
Document all operational procedures

For detailed schema definitions, refer to the OpenAPI specification published alongside the backend service.

Documentation Index

​Nodes API Reference

​Endpoints Overview

​SSH Key Management

​List SSH Keys

​Add SSH Key

​Node Management

​List All Nodes

​Add a New Node

​Get Node Details

​Cloud Instance Management

​Launch Cloud Instance

​Terminate Instance

​Restart Instance

​Connection Management

​Test Connection

​Verify Node

​Execute Command

​Resource Management

​Add Firewall Rule

​Create Volume

​Discovery & Exploration

​Discover Cloud Instances

​Get Instance Types

​Error Responses

​Best Practices

​Security

​Performance

​Automation

Nodes API Reference

Endpoints Overview

SSH Key Management

List SSH Keys

Add SSH Key

Node Management

List All Nodes

Add a New Node

Get Node Details

Cloud Instance Management

Launch Cloud Instance

Terminate Instance

Restart Instance

Connection Management

Test Connection

Verify Node

Execute Command

Resource Management

Add Firewall Rule

Create Volume

Discovery & Exploration

Discover Cloud Instances

Get Instance Types

Error Responses

Best Practices

Security

Performance

Automation