Plaza6G REST API Manual

Plaza6G API Manual

This manual documents the Plaza6G REST API endpoints for managing experiments, infrastructure resources, and network templates.

Overview

• Base URL: http://<PLAZA6G_API_HOST>:5000
• Authentication: API key via header or query parameter

Table of Contents

1. Authentication
2. Infrastructure API
3. Template APIs (UERANSIM, Emulator)
4. User Experiments (List, Delete)

Quick Reference (Cheat Sheet)

Copy/paste the most common API calls. For safety, examples use placeholders.

export PLAZA6G_API_BASE="http://<PLAZA6G_API_HOST>:5000"
export API_KEY="<YOUR_API_KEY>"

Authentication

# Header (Recommended)
-H "X-API-Key: $API_KEY"

# Query parameter (Alternative)
?api_key=$API_KEY

Infrastructure: Create VMs

curl -X POST "$PLAZA6G_API_BASE/api/v1/infrastructure" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "us_id": 11,
    "infra_type": "lxd",
    "experiment_name": "My VM Experiment",
    "vms": [
      {"vm_name": "web-server", "cpu": 2, "ram": 4, "disk": 30},
      {"vm_name": "db-server", "cpu": 4, "ram": 8, "disk": 50}
    ]
  }'

Templates: UERANSIM (Free5GC)

curl -X POST "$PLAZA6G_API_BASE/api/v1/template/ueransim" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "us_id": 11,
    "infra_type": "lxd",
    "experiment_name": "5G Test Network",
    "core_type": "free5gc"
  }'

Templates: Emulator (Open5GS + DNN)

curl -X POST "$PLAZA6G_API_BASE/api/v1/template/emulator" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "us_id": 11,
    "infra_type": "openstack",
    "experiment_name": "Emulator with DNN",
    "core_type": "open5gs",
    "dnn_required": "yes"
  }'

List User Experiments

curl -s -X GET "$PLAZA6G_API_BASE/api/v1/users/experiments?us_id=8" \
  -H "X-API-Key: $API_KEY" | jq '.experiments[] | {ex_id, ex_name, ex_status}'

Delete Experiment (Soft Delete)

curl -X POST "$PLAZA6G_API_BASE/api/v1/users/experiments/delete" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"us_id": 8, "ex_id": 710}'

Common Response Codes

1) Authentication

All endpoints require an API key.

Option 1: Header (Recommended)

X-API-Key: <YOUR_API_KEY>

Option 2: Query Parameter

?api_key=<YOUR_API_KEY>

Error Responses

• 401 Unauthorized: {"success": false, "message": "Invalid API key"}
• 500 Server Error: {"success": false, "message": "PLAZA6G_API_KEY not set"}

2) Infrastructure API

Create experiments with VMs, containers, bare metal servers, and Kubernetes clusters.

Endpoint

POST /api/v1/infrastructure

Required Headers

Content-Type: application/json
X-API-Key: <YOUR_API_KEY>

Required Fields

Resource types: Provide at least one of vms, containers, baremetals, k8s_clusters.

Common Optional Fields

Virtual Machines (VMs)

Required per VM: vm_name, cpu, ram, disk. Optional: gpu.

curl -X POST "http://<PLAZA6G_API_HOST>:5000/api/v1/infrastructure" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "us_id": 11,
    "infra_type": "lxd",
    "experiment_name": "VM Test",
    "vms": [
      {"vm_name": "vm-1", "cpu": 2, "ram": 4, "disk": 30},
      {"vm_name": "vm-2", "cpu": 4, "ram": 8, "disk": 50}
    ]
  }'

Containers

curl -X POST "http://<PLAZA6G_API_HOST>:5000/api/v1/infrastructure" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "us_id": 11,
    "infra_type": "lxd",
    "experiment_name": "Container Test",
    "containers": [
      {"container_name": "co-1", "cpu": 2, "ram": 4, "disk": 30}
    ]
  }'

Bare Metal Servers

curl -X POST "http://<PLAZA6G_API_HOST>:5000/api/v1/infrastructure" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "us_id": 11,
    "infra_type": "openstack",
    "experiment_name": "Bare Metal Test",
    "baremetals": [
      {"bare_metal_name": "bm-1", "cpu": 8, "ram": 32, "disk": 200}
    ]
  }'

Kubernetes Clusters

Creates 1 master + (num_nodes - 1) workers.

curl -X POST "http://<PLAZA6G_API_HOST>:5000/api/v1/infrastructure" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "us_id": 11,
    "infra_type": "lxd",
    "experiment_name": "K8s Test",
    "k8s_clusters": [
      {"kc_name": "cluster-1", "num_nodes": 3, "cpu": 2, "ram": 4, "disk_size": 30}
    ]
  }'

3) Template APIs

Pre-configured templates for common network scenarios.

UERANSIM Template

POST /api/v1/template/ueransim

Required: us_id, infra_type, experiment_name, core_type

core_type: free5gc | open5gs | openairinterface

Optional: dnn_required (yes/no), cpu, ram

curl -X POST "http://<PLAZA6G_API_HOST>:5000/api/v1/template/ueransim" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "us_id": 11,
    "infra_type": "lxd",
    "experiment_name": "UERANSIM Free5GC",
    "core_type": "free5gc",
    "dnn_required": "yes"
  }'

Emulator Template

POST /api/v1/template/emulator

Required: us_id, infra_type, experiment_name, core_type

Optional: dnn_required, attenuation (simulated)

curl -X POST "http://<PLAZA6G_API_HOST>:5000/api/v1/template/emulator" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "us_id": 11,
    "infra_type": "openstack",
    "experiment_name": "Emulator with Attenuation",
    "core_type": "open5gs",
    "dnn_required": "no",
    "attenuation": {
      "atten_AB_input": 10,
      "atten_AC_input": 5,
      "atten_AD_input": 0,
      "atten_BD_input": 0,
      "atten_CD_input": 0,
      "atten_BC_input": 0
    }
  }'

4) User Experiments

List Experiments

GET /api/v1/users/experiments?us_id=<USER_ID>

curl -X GET "http://<PLAZA6G_API_HOST>:5000/api/v1/users/experiments?us_id=8" \
  -H "X-API-Key: <YOUR_API_KEY>"

Delete Experiment (Soft Delete)

POST /api/v1/users/experiments/delete

curl -X POST "http://<PLAZA6G_API_HOST>:5000/api/v1/users/experiments/delete" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"us_id": 8, "ex_id": 756}'

Common Error Codes

Notes & Best Practices

• Never commit API keys to version control.
• Delete operations are idempotent.
• Don’t rely on JSON field ordering.
• Deleted experiments are filtered out of list endpoints.
• Default IP 0.0.0.0 is a placeholder (assigned on deploy).

Last Updated: February 2026