Networking

VLAN

Allowed HTTP methods

Method

Description

GET

get / list VLANs

PUT

edit VLANs meta

Note

See RFC 2616#section-9 for more details on HTTP methods semantics

Listing

GET /vlans/

Gets the list of VLANs to which the authenticated user has access.

statuscode 200:

no error

Example request:

GET /api/2.0/vlans/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
            "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
        }
    ]
}

Detailed listing

GET /vlans/detail/
statuscode 200:

no error

Example request:

GET /api/2.0/vlans/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "bottom_vlan_tag": null,
            "grantees": [],
            "meta": {},
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
            "servers": [],
            "subscription": {
                "id": 12,
                "resource_uri": "/api/2.0/subscriptions/12/"
            },
            "tags": [],
            "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
        }
    ]
}

Get single VLAN

GET /vlans/(uuid: vlan_uuid)/
statuscode 200:

no error

Example request:

GET /api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "bottom_vlan_tag": null,
    "grantees": [],
    "meta": {},
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
    "servers": [],
    "subscription": {
        "id": 12,
        "resource_uri": "/api/2.0/subscriptions/12/"
    },
    "tags": [],
    "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
}

Creating

New VLANs are created by buying a subscription. See Subscriptions.

Editing

Currently only VLAN meta field can be edited.

PUT /vlans/(uuid: vlan_uuid)/
statuscode 200:

no error

Example request:

PUT /api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "meta": {
        "custom_field": "some custom data",
        "name": "my vlan"
    }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "bottom_vlan_tag": null,
    "grantees": [],
    "meta": {
        "custom_field": "some custom data",
        "name": "my vlan"
    },
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/vlans/10619300-edda-42ba-91e0-7e3df0689d00/",
    "servers": [],
    "subscription": {
        "id": 12,
        "resource_uri": "/api/2.0/subscriptions/12/"
    },
    "tags": [],
    "uuid": "10619300-edda-42ba-91e0-7e3df0689d00"
}

Metadata

It is possible to add arbitrary key-value data to a VLAN definition. See Objects’ metadata field for more information.

Deleting

Not applicable - The VLAN will disappear when the subscription for it expires.

Attaching To servers

A VLAN can be attached to multiple servers. See Server Network Interfaces for more information on using VLANs in NIC configurations.

IPs

The IP object, contains the actual IP in it’s uuid attribute.

The list of IPs includes the IPs that are owned (subscribed to) by the user, and the IPs which are dynamically assigned to user’s servers. The owned IP’s are differentiated by dynamically received IPs by the fact that they have a subscription attached to them (their subscription attribute is not empty).

The detailed listing includes more information about the IP object, such as netmask, nameservers, and gateway which will be set on the NIC. The netmask value is in CIDR notation (/24 for a 255.255.255.0 mask). The nameservers attribute contains a list of DNS servers, which will be assigned through DHCP, and the gateway attribute contains the IP of the default gateway for the current IP.

Allowed HTTP methods

Method

Description

GET

get / list IPs

PUT

edit IP metadata

Note

See RFC 2616#section-9 for more details on HTTP methods semantics

Listing

GET /ips/

Gets the list of IPSs to which the authenticated user has access.

statuscode 200:

no error

Example request:

GET /api/2.0/ips/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/ips/185.12.6.183/",
            "server": null,
            "uuid": "185.12.6.183"
        }
    ]
}

Detailed listing

GET /ips/detail/
statuscode 200:

no error

Example request:

GET /api/2.0/ips/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "gateway": "185.12.6.1",
            "grantees": [],
            "meta": {},
            "nameservers": [
                "69.194.139.62",
                "178.22.66.167",
                "178.22.71.56"
            ],
            "netmask": 24,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/ips/185.12.6.183/",
            "server": null,
            "subscription": {
                "id": 7273,
                "resource_uri": "/api/2.0/subscriptions/7273/"
            },
            "tags": [],
            "uuid": "185.12.6.183"
        }
    ]
}

Get single IP

GET /ips/(uuid: ip_uuid)/
statuscode 200:

no error

Example request:

GET /api/2.0/ips/185.12.6.183/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "gateway": "185.12.6.1",
    "grantees": [],
    "meta": {},
    "nameservers": [
        "69.194.139.62",
        "178.22.66.167",
        "178.22.71.56"
    ],
    "netmask": 24,
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/ips/185.12.6.183/",
    "server": null,
    "subscription": {
        "id": 7273,
        "resource_uri": "/api/2.0/subscriptions/7273/"
    },
    "tags": [],
    "uuid": "185.12.6.183"
}

Creating

New IPs are created by buying a subscription. See Subscriptions.

Editing

Currently only IP meta field can be edited.

PUT /ips/(uuid: ip_uuid)/
statuscode 200:

no error

Example request:

PUT /api/2.0/ips/185.12.6.183/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "meta": {
        "custom_field": "some custom data",
        "name": "my ip"
    }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "gateway": "185.12.6.1",
    "grantees": [],
    "meta": {
        "custom_field": "some custom data",
        "name": "my ip"
    },
    "nameservers": [
        "69.194.139.62",
        "178.22.66.167",
        "178.22.71.56"
    ],
    "netmask": 24,
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/ips/185.12.6.183/",
    "server": null,
    "subscription": {
        "id": 7273,
        "resource_uri": "/api/2.0/subscriptions/7273/"
    },
    "tags": [],
    "uuid": "185.12.6.183"
}

Metadata

It is possible to add arbitrary key-value data to an IP definition. See Objects’ metadata field for more information.

Deleting

Not applicable - The IP will disappear when the subscription for it expires.

Attaching To servers

An IP can be attached to a single server. To check whether IP is currently attached to a server look at the attribute on the object in the detailed listing or on single object retrieval. If server is empty, then the IP is not attached to a server and can be used for static IP configuration. See Server Network Interfaces for more information on using IPs in NIC configurations.

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "put"
    ],
    "allowed_list_http_methods": "get",
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "bottom_vlan_tag": {
            "default": null,
            "help_text": "Integer data. Ex: 2673",
            "readonly": true,
            "required": false,
            "type": "integer"
        },
        "grantees": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "meta": {
            "default": {},
            "help_text": "User defined meta information",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "owner": {
            "default": null,
            "help_text": "VLAN owner",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "permissions": {
            "default": "No default provided.",
            "help_text": "A list of data. Ex: ['abc', 26.73, 8]",
            "readonly": false,
            "required": false,
            "type": "list"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "servers": {
            "default": [],
            "help_text": "Servers in this VLAN",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "subscription": {
            "default": null,
            "help_text": "Subscription related to this VLAN",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "VLAN UUID",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}