VPC API

Base URL: https://api.sparbz.cloud/api/v1

Overview

The VPC API allows you to create and manage Virtual Private Clouds (VPCs) for network isolation and resource organization. Create VPCs with custom CIDR blocks, manage subnets, configure routing, and control network access.

All endpoints require authentication via Bearer token or API key.

VPC Management

GET /vpcs

List all VPCs in your organization.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Description
region	string	Filter by region (us-east-1, eu-west-1, etc.)
status	string	Filter by status: `provisioning`, `available`, `deleting`, `deleted`
limit	integer	Number of results (default: 20, max: 100)
offset	integer	Pagination offset

Response (200 OK):

[
  {
    "id": "uuid",
    "name": "production-vpc",
    "cidr_block": "10.0.0.0/16",
    "region": "us-east-1",
    "status": "available",
    "is_default": false,
    "subnet_count": 3,
    "route_table_count": 2,
    "nat_gateway_count": 1,
    "flow_logs_enabled": true,
    "created_at": "2024-10-15T10:30:00Z"
  }
]

POST /vpcs

Create a new VPC.

Request Body:

{
  "name": "string",
  "cidr_block": "string (CIDR notation)",
  "region": "string",
  "enable_dns_hostnames": true,
  "enable_dns_support": true,
  "enable_flow_logs": false
}

Response (201 Created):

{
  "id": "uuid",
  "name": "production-vpc",
  "cidr_block": "10.0.0.0/16",
  "region": "us-east-1",
  "status": "provisioning",
  "is_default": false,
  "created_at": "2024-11-29T10:30:00Z"
}

GET /vpcs/:id

Get details of a specific VPC.

Response (200 OK):

{
  "id": "uuid",
  "name": "production-vpc",
  "cidr_block": "10.0.0.0/16",
  "region": "us-east-1",
  "status": "available",
  "is_default": false,
  "enable_dns_hostnames": true,
  "enable_dns_support": true,
  "enable_flow_logs": true,
  "flow_logs_destination": "arn:aws:s3:::bucket/vpc-logs",
  "subnet_count": 3,
  "route_table_count": 2,
  "nat_gateway_count": 1,
  "internet_gateway_count": 1,
  "security_group_count": 5,
  "network_acl_count": 1,
  "created_at": "2024-10-15T10:30:00Z",
  "updated_at": "2024-11-29T15:45:00Z"
}

PATCH /vpcs/:id

Update VPC settings.

Request Body:

{
  "name": "string (optional)",
  "enable_dns_hostnames": boolean,
  "enable_dns_support": boolean,
  "enable_flow_logs": boolean
}

Response (200 OK):

{
  "id": "uuid",
  "name": "production-vpc-updated",
  "updated_at": "2024-11-29T15:45:00Z"
}

DELETE /vpcs/:id

Delete a VPC.

Response (204 No Content)

Subnet Management

GET /vpcs/:id/subnets

List all subnets in a VPC.

Response (200 OK):

[
  {
    "id": "uuid",
    "name": "public-subnet-1a",
    "cidr_block": "10.0.1.0/24",
    "availability_zone": "us-east-1a",
    "available_ip_count": 251,
    "map_public_ip_on_launch": true,
    "route_table_id": "rtb-xxx",
    "created_at": "2024-10-15T10:30:00Z"
  }
]

POST /vpcs/:id/subnets

Create a new subnet in a VPC.

Request Body:

{
  "name": "string",
  "cidr_block": "string",
  "availability_zone": "string",
  "map_public_ip_on_launch": false
}

Response (201 Created):

{
  "id": "uuid",
  "name": "public-subnet-1a",
  "cidr_block": "10.0.1.0/24",
  "availability_zone": "us-east-1a",
  "available_ip_count": 251,
  "created_at": "2024-11-29T10:30:00Z"
}

GET /vpcs/:id/subnets/:subnet_id

Get details of a specific subnet.

Response (200 OK):

{
  "id": "uuid",
  "name": "public-subnet-1a",
  "cidr_block": "10.0.1.0/24",
  "availability_zone": "us-east-1a",
  "available_ip_count": 251,
  "assigned_ip_count": 5,
  "map_public_ip_on_launch": true,
  "route_table_id": "rtb-xxx",
  "network_acl_id": "acl-xxx",
  "created_at": "2024-10-15T10:30:00Z"
}

DELETE /vpcs/:id/subnets/:subnet_id

Delete a subnet.

Response (204 No Content)

Security Groups

GET /vpcs/:id/security-groups

List all security groups in a VPC.

Response (200 OK):

[
  {
    "id": "sg-xxx",
    "name": "web-sg",
    "description": "Security group for web servers",
    "inbound_rules": [
      {
        "protocol": "tcp",
        "port_range": "80-80",
        "source": "0.0.0.0/0"
      }
    ],
    "outbound_rules": [
      {
        "protocol": "-1",
        "source": "0.0.0.0/0"
      }
    ]
  }
]

POST /vpcs/:id/security-groups

Create a new security group.

Request Body:

{
  "name": "string",
  "description": "string",
  "inbound_rules": [
    {
      "protocol": "tcp | udp | icmp",
      "port_range": "string (e.g., 80-80, 3306-3306)",
      "source": "CIDR or security group id"
    }
  ]
}

Response (201 Created):

{
  "id": "sg-xxx",
  "name": "web-sg",
  "description": "Security group for web servers",
  "created_at": "2024-11-29T10:30:00Z"
}

Network ACLs

GET /vpcs/:id/network-acls

List all Network ACLs in a VPC.

Response (200 OK):

[
  {
    "id": "acl-xxx",
    "is_default": false,
    "inbound_rules": [
      {
        "rule_number": 100,
        "protocol": "tcp",
        "port_range": "80-80",
        "source": "0.0.0.0/0",
        "action": "allow"
      }
    ],
    "outbound_rules": [
      {
        "rule_number": 100,
        "protocol": "-1",
        "action": "allow"
      }
    ]
  }
]

Route Tables

GET /vpcs/:id/route-tables

List all route tables in a VPC.

Response (200 OK):

[
  {
    "id": "rtb-xxx",
    "name": "public-routes",
    "routes": [
      {
        "destination": "10.0.0.0/16",
        "target": "local"
      },
      {
        "destination": "0.0.0.0/0",
        "target": "igw-xxx"
      }
    ],
    "subnet_associations": 2
  }
]

POST /vpcs/:id/route-tables/:rtb_id/routes

Add a route to a route table.

Request Body:

{
  "destination_cidr_block": "string",
  "target": "internet_gateway | nat_gateway | vpn_gateway | instance | network_interface"
}

Response (201 Created)

Internet Gateways

POST /vpcs/:id/internet-gateways

Attach an Internet Gateway to a VPC.

Request Body:

{
  "name": "string"
}

Response (201 Created):

{
  "id": "igw-xxx",
  "name": "main-igw",
  "status": "available",
  "created_at": "2024-11-29T10:30:00Z"
}

GET /vpcs/:id/internet-gateways

List Internet Gateways attached to a VPC.

Response (200 OK):

[
  {
    "id": "igw-xxx",
    "name": "main-igw",
    "status": "available",
    "created_at": "2024-10-15T10:30:00Z"
  }
]

NAT Gateways

GET /vpcs/:id/nat-gateways

List NAT Gateways in a VPC.

Response (200 OK):

[
  {
    "id": "nat-xxx",
    "status": "available",
    "public_ip": "203.0.113.1",
    "elastic_ip_allocation_id": "eipalloc-xxx",
    "subnet_id": "subnet-xxx",
    "created_at": "2024-10-15T10:30:00Z"
  }
]

POST /vpcs/:id/nat-gateways

Create a NAT Gateway.

Request Body:

{
  "subnet_id": "string",
  "allocation_id": "string (elastic IP allocation)"
}

Response (201 Created):

{
  "id": "nat-xxx",
  "status": "pending",
  "created_at": "2024-11-29T10:30:00Z"
}

Error Responses

Code	Description
400	Bad Request - Invalid CIDR block, region, or subnet configuration
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - VPC, subnet, or related resource doesn't exist
409	Conflict - CIDR block overlaps or resource already exists
429	Too Many Requests - VPC limit reached
500	Internal Server Error

Common Use Cases

Creating a Production VPC with Public and Private Subnets

# Create VPC
POST /vpcs
{
  "name": "production",
  "cidr_block": "10.0.0.0/16",
  "region": "us-east-1"
}

# Create public subnet
POST /vpcs/{vpc_id}/subnets
{
  "name": "public-1a",
  "cidr_block": "10.0.1.0/24",
  "availability_zone": "us-east-1a",
  "map_public_ip_on_launch": true
}

# Create private subnet
POST /vpcs/{vpc_id}/subnets
{
  "name": "private-1a",
  "cidr_block": "10.0.10.0/24",
  "availability_zone": "us-east-1a"
}

Setting Up Internet Access

# Create and attach Internet Gateway
POST /vpcs/{vpc_id}/internet-gateways
{
  "name": "main-igw"
}

# Add route to Internet Gateway
POST /vpcs/{vpc_id}/route-tables/{rtb_id}/routes
{
  "destination_cidr_block": "0.0.0.0/0",
  "target": "internet_gateway"
}

Creating a Web Server Security Group

POST /vpcs/{vpc_id}/security-groups
{
  "name": "web-servers",
  "description": "Allow HTTP and HTTPS",
  "inbound_rules": [
    {
      "protocol": "tcp",
      "port_range": "80-80",
      "source": "0.0.0.0/0"
    },
    {
      "protocol": "tcp",
      "port_range": "443-443",
      "source": "0.0.0.0/0"
    }
  ]
}

Overview​

VPC Management​

GET /vpcs​

POST /vpcs​

GET /vpcs/:id​

PATCH /vpcs/:id​

DELETE /vpcs/:id​

Subnet Management​

GET /vpcs/:id/subnets​

POST /vpcs/:id/subnets​

GET /vpcs/:id/subnets/:subnet_id​

DELETE /vpcs/:id/subnets/:subnet_id​

Security Groups​

GET /vpcs/:id/security-groups​

POST /vpcs/:id/security-groups​

Network ACLs​

GET /vpcs/:id/network-acls​

Route Tables​

GET /vpcs/:id/route-tables​

POST /vpcs/:id/route-tables/:rtb_id/routes​

Internet Gateways​

POST /vpcs/:id/internet-gateways​

GET /vpcs/:id/internet-gateways​

NAT Gateways​

GET /vpcs/:id/nat-gateways​

POST /vpcs/:id/nat-gateways​

Error Responses​

Common Use Cases​

Creating a Production VPC with Public and Private Subnets​

Setting Up Internet Access​

Creating a Web Server Security Group​

Overview

VPC Management

GET /vpcs

POST /vpcs

GET /vpcs/:id

PATCH /vpcs/:id

DELETE /vpcs/:id

Subnet Management

GET /vpcs/:id/subnets

POST /vpcs/:id/subnets

GET /vpcs/:id/subnets/:subnet_id

DELETE /vpcs/:id/subnets/:subnet_id

Security Groups

GET /vpcs/:id/security-groups

POST /vpcs/:id/security-groups

Network ACLs

GET /vpcs/:id/network-acls

Route Tables

GET /vpcs/:id/route-tables

POST /vpcs/:id/route-tables/:rtb_id/routes

Internet Gateways

POST /vpcs/:id/internet-gateways

GET /vpcs/:id/internet-gateways

NAT Gateways

GET /vpcs/:id/nat-gateways

POST /vpcs/:id/nat-gateways

Error Responses

Common Use Cases

Creating a Production VPC with Public and Private Subnets

Setting Up Internet Access

Creating a Web Server Security Group