Network Registry — Developer Docs

1) Data Model

@dataclass
class NetworkObject:
    network_id: str = ''
    network_name: str = ''
    metadata: Dict[str, Any] = field(default_factory=dict)
    services_map: Dict[str, str] = field(default_factory=dict)
    policies: Dict[str, str] = field(default_factory=dict)

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> 'NetworkObject':
        return cls(
            network_id=data.get('network_id', ''),
            network_name=data.get('network_name', ''),
            metadata=data.get('metadata', {}),
            services_map=data.get('services_map', {}),
            policies=data.get('policies', {})
        )

    def to_dict(self) -> Dict[str, Any]:
        return {
            'network_id': self.network_id,
            'network_name': self.network_name,
            'metadata': self.metadata,
            'services_map': self.services_map,
            'policies': self.policies
        }

`NetworkObject` (Python `@dataclass`)

Field	Type	Required	Default	Description	Example
`network_id`	`str`	✔️*	`''`	Unique, stable identifier of the network. Used as the primary lookup key.	`"net-001"`
`network_name`	`str`	✔️*	`''`	Human-readable name for the network.	`"West-Coast GPU Mesh"`
`metadata`	`Dict[str, Any]`	❌	`{}`	Arbitrary key–value metadata (owner, region, tags, created_at, etc.).	`{"owner":"ops@acme.io","region":"us-west"}`
`services_map`	`Dict[str, str]`	❌	`{}`	Logical service → URL/DNS mapping for discovery.	`{"metrics":"http://metrics.svc:8888", "gateway":"https://gw.example.com"}`
`policies`	`Dict[str, str]`	❌	`{}`	Policy name → URI/ID/version reference (or inline policy IDs).	`{"quota":"policy://quota/v1","admission":"policy://admission/v2"}`

* Although the dataclass provides empty-string defaults, your DB layer should treat network_id (and usually network_name) as required and validate accordingly.

Serialization helpers

NetworkObject.from_dict(data: Dict[str, Any]) -> NetworkObject
NetworkObject.to_dict() -> Dict[str, Any]

2) REST APIs

Base URL: http://<host>:5000 Content-Type: application/json

Create Network

POST /network

Creates a new network document.

Request body (JSON)

{
  "network_id": "net-001",
  "network_name": "West-Coast GPU Mesh",
  "metadata": { "owner": "ops@acme.io", "region": "us-west" },
  "services_map": { "metrics": "http://metrics.svc:8888" },
  "policies": { "quota": "policy://quota/v1" }
}

Success response

{
  "success": true,
  "data": { "message": "Network created", "id": "66f...abc" }
}

Status: 201 Created

Failure response

{ "success": false, "error": "duplicate network_id" }

Status: 400 Bad Request (validation/duplicate) or 500 Internal Server Error

cURL

curl -sS -X POST http://localhost:5000/network \
  -H "Content-Type: application/json" \
  -d '{
    "network_id": "net-001",
    "network_name": "West-Coast GPU Mesh",
    "metadata": { "owner": "ops@acme.io", "region": "us-west" },
    "services_map": { "metrics": "http://metrics.svc:8888" },
    "policies": { "quota": "policy://quota/v1" }
  }'

Get Network by ID

GET /network/{network_id}

Fetches a single network.

Path params

network_id — the unique ID (e.g., net-001)

Success response

{
  "success": true,
  "data": {
    "network_id": "net-001",
    "network_name": "West-Coast GPU Mesh",
    "metadata": { "owner": "ops@acme.io", "region": "us-west" },
    "services_map": { "metrics": "http://metrics.svc:8888" },
    "policies": { "quota": "policy://quota/v1" }
  }
}

Status: 200 OK

Not found

{ "success": false, "error": "network not found" }

Status: 404 Not Found

cURL

curl -sS http://localhost:5000/network/net-001

Update Network (partial or full)

PUT /network/{network_id}

Updates fields for an existing network. The body can include any subset of fields to change.

Path params

network_id

Request body (JSON) — example

{
  "network_name": "West-Coast Mesh (Prod)",
  "services_map": {
    "metrics": "http://metrics.svc:8888",
    "gateway": "https://gw.example.com"
  }
}

Success response

{ "success": true, "data": { "message": "Network updated" } }

Status: 200 OK

Not found

{ "success": false, "error": "network not found" }

Status: 404 Not Found

cURL

curl -sS -X PUT http://localhost:5000/network/net-001 \
  -H "Content-Type: application/json" \
  -d '{
    "network_name": "West-Coast Mesh (Prod)",
    "services_map": {
      "metrics": "http://metrics.svc:8888",
      "gateway": "https://gw.example.com"
    }
  }'

Delete Network

DELETE /network/{network_id}

Deletes the network document.

Success response

{ "success": true, "data": { "message": "Network deleted" } }

Status: 200 OK

Not found

{ "success": false, "error": "network not found" }

Status: 404 Not Found

cURL

curl -sS -X DELETE http://localhost:5000/network/net-001

Query Networks (filter search)

POST /networks

Executes a filter query. The exact semantics depend on your NetworkDatabase.query implementation. Typical filters:

Direct equality on top-level fields: network_id, network_name
Nested field matches (e.g., metadata.owner)
Contains/exists checks depending on DB layer

Request body (JSON) — examples

By network_name:

{ "network_name": "West-Coast GPU Mesh" }

By nested metadata:

{ "metadata.owner": "ops@acme.io" }

Multiple filters:

{
  "metadata.region": "us-west",
  "services_map.metrics": { "$exists": true }
}

Success response

{
  "success": true,
  "data": [
    {
      "network_id": "net-001",
      "network_name": "West-Coast GPU Mesh",
      "metadata": { "owner": "ops@acme.io", "region": "us-west" },
      "services_map": { "metrics": "http://metrics.svc:8888" },
      "policies": { "quota": "policy://quota/v1" }
    }
  ]
}

Status: 200 OK

Failure response

{ "success": false, "error": "invalid filter syntax" }

Status: 400 Bad Request or 500 Internal Server Error

cURL

# Query by owner
curl -sS -X POST http://localhost:5000/networks \
  -H "Content-Type: application/json" \
  -d '{ "metadata.owner": "ops@acme.io" }'

3) Notes & Best Practices

Validation: Even though the dataclass has defaults, enforce:
network_id: non-empty, unique, immutable (on update).
network_name: non-empty (recommended).
Idempotency:
POST /network should fail on duplicate network_id (409/400).
PUT /network/{id} should not change network_id.
Partial Updates: Current PUT accepts partial fields. If you need JSON Patch/merge semantics, document them explicitly.
Error Handling: Return concise, actionable errors (error string) with appropriate status codes.
Security: Add auth (e.g., API keys/JWT) and input sanitization as needed.

Network Registry — Developer Docs

1) Data Model

NetworkObject (Python @dataclass)

2) REST APIs

Create Network

Get Network by ID

Update Network (partial or full)

Delete Network

Query Networks (filter search)

3) Notes & Best Practices

`NetworkObject` (Python `@dataclass`)