From 5045c6cfbfab402cbaade4d7c433e707a03411ba Mon Sep 17 00:00:00 2001 From: grossmj Date: Thu, 28 Mar 2019 17:24:02 +0800 Subject: [PATCH] Update documentation --- .../controller_delete_templatestemplateid.txt | 14 ++ .../api/examples/controller_get_templates.txt | 121 ++++++++++++++++++ .../controller_get_templatestemplateid.txt | 28 ++++ .../examples/controller_post_templates.txt | 65 ++++++++++ ...ller_post_templatestemplateidduplicate.txt | 27 ++++ .../controller_put_templatestemplateid.txt | 38 ++++++ docs/api/v2/controller/template.rst | 8 ++ .../projectsprojectidtemplatestemplateid.rst | 64 +++++++++ docs/api/v2/controller/template/templates.rst | 67 ++++++++++ .../template/templatestemplateid.rst | 107 ++++++++++++++++ .../template/templatestemplateidduplicate.rst | 41 ++++++ 11 files changed, 580 insertions(+) create mode 100644 docs/api/examples/controller_delete_templatestemplateid.txt create mode 100644 docs/api/examples/controller_get_templates.txt create mode 100644 docs/api/examples/controller_get_templatestemplateid.txt create mode 100644 docs/api/examples/controller_post_templates.txt create mode 100644 docs/api/examples/controller_post_templatestemplateidduplicate.txt create mode 100644 docs/api/examples/controller_put_templatestemplateid.txt create mode 100644 docs/api/v2/controller/template.rst create mode 100644 docs/api/v2/controller/template/projectsprojectidtemplatestemplateid.rst create mode 100644 docs/api/v2/controller/template/templates.rst create mode 100644 docs/api/v2/controller/template/templatestemplateid.rst create mode 100644 docs/api/v2/controller/template/templatestemplateidduplicate.rst diff --git a/docs/api/examples/controller_delete_templatestemplateid.txt b/docs/api/examples/controller_delete_templatestemplateid.txt new file mode 100644 index 00000000..0bede843 --- /dev/null +++ b/docs/api/examples/controller_delete_templatestemplateid.txt @@ -0,0 +1,14 @@ +curl -i -X DELETE 'http://localhost:3080/v2/templates/f25c50bb-c5fa-4194-b657-9246908d573e' + +DELETE /v2/templates/f25c50bb-c5fa-4194-b657-9246908d573e HTTP/1.1 + + + +HTTP/1.1 204 +Connection: close +Content-Length: 0 +Content-Type: application/octet-stream +Date: Tue, 27 Nov 2018 15:09:55 GMT +Server: Python/3.6 GNS3/2.2.0dev5 +X-Route: /v2/templates/{template_id} + diff --git a/docs/api/examples/controller_get_templates.txt b/docs/api/examples/controller_get_templates.txt new file mode 100644 index 00000000..fa7c48ab --- /dev/null +++ b/docs/api/examples/controller_get_templates.txt @@ -0,0 +1,121 @@ +curl -i -X GET 'http://localhost:3080/v2/templates' + +GET /v2/templates HTTP/1.1 + + + +HTTP/1.1 200 +Connection: close +Content-Length: 3193 +Content-Type: application/json +Date: Tue, 27 Nov 2018 15:09:55 GMT +Server: Python/3.6 GNS3/2.2.0dev5 +X-Route: /v2/templates + +[ + { + "builtin": true, + "category": "guest", + "name": "Cloud", + "symbol": ":/symbols/cloud.svg", + "template_id": "39e257dc-8412-3174-b6b3-0ee3ed6a43e9", + "template_type": "cloud" + }, + { + "builtin": true, + "category": "guest", + "name": "NAT", + "symbol": ":/symbols/cloud.svg", + "template_id": "df8f4ea9-33b7-3e96-86a2-c39bc9bb649c", + "template_type": "nat" + }, + { + "builtin": true, + "category": "guest", + "default_name_format": "PC-{0}", + "name": "VPCS", + "properties": { + "base_script_file": "vpcs_base_config.txt" + }, + "symbol": ":/symbols/vpcs_guest.svg", + "template_id": "19021f99-e36f-394d-b4a1-8aaa902ab9cc", + "template_type": "vpcs" + }, + { + "builtin": true, + "category": "switch", + "console_type": "telnet", + "name": "Ethernet switch", + "symbol": ":/symbols/ethernet_switch.svg", + "template_id": "1966b864-93e7-32d5-965f-001384eec461", + "template_type": "ethernet_switch" + }, + { + "builtin": true, + "category": "switch", + "name": "Ethernet hub", + "symbol": ":/symbols/hub.svg", + "template_id": "b4503ea9-d6b6-3695-9fe4-1db3b39290b0", + "template_type": "ethernet_hub" + }, + { + "builtin": true, + "category": "switch", + "name": "Frame Relay switch", + "symbol": ":/symbols/frame_relay_switch.svg", + "template_id": "dd0f6f3a-ba58-3249-81cb-a1dd88407a47", + "template_type": "frame_relay_switch" + }, + { + "builtin": true, + "category": "switch", + "name": "ATM switch", + "symbol": ":/symbols/atm_switch.svg", + "template_id": "aaa764e2-b383-300f-8a0e-3493bbfdb7d2", + "template_type": "atm_switch" + }, + { + "adapter_type": "e1000", + "adapters": 1, + "bios_image": "", + "boot_priority": "c", + "builtin": false, + "category": "router", + "cdrom_image": "", + "compute_id": "local", + "console_auto_start": false, + "console_type": "telnet", + "cpu_throttling": 0, + "cpus": 1, + "custom_adapters": [], + "default_name_format": "{name}-{0}", + "first_port_name": "", + "hda_disk_image": "", + "hda_disk_interface": "ide", + "hdb_disk_image": "", + "hdb_disk_interface": "ide", + "hdc_disk_image": "", + "hdc_disk_interface": "ide", + "hdd_disk_image": "", + "hdd_disk_interface": "ide", + "initrd": "", + "kernel_command_line": "", + "kernel_image": "", + "legacy_networking": false, + "linked_clone": true, + "mac_address": "", + "name": "test", + "on_close": "power_off", + "options": "", + "platform": "i386", + "port_name_format": "Ethernet{0}", + "port_segment_size": 0, + "process_priority": "normal", + "qemu_path": "", + "ram": 256, + "symbol": "guest.svg", + "template_id": "64aca851-88e1-48ae-a562-b5084a67dc28", + "template_type": "qemu", + "usage": "" + } +] diff --git a/docs/api/examples/controller_get_templatestemplateid.txt b/docs/api/examples/controller_get_templatestemplateid.txt new file mode 100644 index 00000000..9434b5a5 --- /dev/null +++ b/docs/api/examples/controller_get_templatestemplateid.txt @@ -0,0 +1,28 @@ +curl -i -X GET 'http://localhost:3080/v2/templates/05abf56b-649b-4ce6-b943-9af1d1f5d9c5' + +GET /v2/templates/05abf56b-649b-4ce6-b943-9af1d1f5d9c5 HTTP/1.1 + + + +HTTP/1.1 200 +Connection: close +Content-Length: 378 +Content-Type: application/json +Date: Tue, 27 Nov 2018 15:09:55 GMT +ETag: "dd3b80f43881170e23c78623f6dfa96c" +Server: Python/3.6 GNS3/2.2.0dev5 +X-Route: /v2/templates/{template_id} + +{ + "base_script_file": "vpcs_base_config.txt", + "builtin": false, + "category": "guest", + "compute_id": "local", + "console_auto_start": false, + "console_type": "telnet", + "default_name_format": "PC{0}", + "name": "VPCS_TEST", + "symbol": ":/symbols/vpcs_guest.svg", + "template_id": "05abf56b-649b-4ce6-b943-9af1d1f5d9c5", + "template_type": "vpcs" +} diff --git a/docs/api/examples/controller_post_templates.txt b/docs/api/examples/controller_post_templates.txt new file mode 100644 index 00000000..d4606d7e --- /dev/null +++ b/docs/api/examples/controller_post_templates.txt @@ -0,0 +1,65 @@ +curl -i -X POST 'http://localhost:3080/v2/templates' -d '{"compute_id": "local", "hda_disk_image": "IOSvL2-15.2.4.0.55E.qcow2", "name": "Qemu template", "platform": "i386", "ram": 512, "template_type": "qemu"}' + +POST /v2/templates HTTP/1.1 +{ + "compute_id": "local", + "hda_disk_image": "IOSvL2-15.2.4.0.55E.qcow2", + "name": "Qemu template", + "platform": "i386", + "ram": 512, + "template_type": "qemu" +} + + +HTTP/1.1 201 +Connection: close +Content-Length: 1194 +Content-Type: application/json +Date: Tue, 27 Nov 2018 15:10:09 GMT +Server: Python/3.6 GNS3/2.2.0dev5 +X-Route: /v2/templates + +{ + "adapter_type": "e1000", + "adapters": 1, + "bios_image": "", + "boot_priority": "c", + "builtin": false, + "category": "guest", + "cdrom_image": "", + "compute_id": "local", + "console_auto_start": false, + "console_type": "telnet", + "cpu_throttling": 0, + "cpus": 1, + "custom_adapters": [], + "default_name_format": "{name}-{0}", + "first_port_name": "", + "hda_disk_image": "IOSvL2-15.2.4.0.55E.qcow2", + "hda_disk_interface": "ide", + "hdb_disk_image": "", + "hdb_disk_interface": "ide", + "hdc_disk_image": "", + "hdc_disk_interface": "ide", + "hdd_disk_image": "", + "hdd_disk_interface": "ide", + "initrd": "", + "kernel_command_line": "", + "kernel_image": "", + "legacy_networking": false, + "linked_clone": true, + "mac_address": "", + "name": "Qemu template", + "on_close": "power_off", + "options": "", + "platform": "i386", + "port_name_format": "Ethernet{0}", + "port_segment_size": 0, + "process_priority": "normal", + "qemu_path": "", + "ram": 512, + "symbol": ":/symbols/qemu_guest.svg", + "template_id": "882c13d9-3bf4-428b-9cb4-3989b01d0524", + "template_type": "qemu", + "usage": "" +} diff --git a/docs/api/examples/controller_post_templatestemplateidduplicate.txt b/docs/api/examples/controller_post_templatestemplateidduplicate.txt new file mode 100644 index 00000000..66c61c36 --- /dev/null +++ b/docs/api/examples/controller_post_templatestemplateidduplicate.txt @@ -0,0 +1,27 @@ +curl -i -X POST 'http://localhost:3080/v2/templates/275526cf-5ae0-4f98-abca-d480b2d4e1f0/duplicate' -d '{}' + +POST /v2/templates/275526cf-5ae0-4f98-abca-d480b2d4e1f0/duplicate HTTP/1.1 +{} + + +HTTP/1.1 201 +Connection: close +Content-Length: 378 +Content-Type: application/json +Date: Tue, 27 Nov 2018 15:09:55 GMT +Server: Python/3.6 GNS3/2.2.0dev5 +X-Route: /v2/templates/{template_id}/duplicate + +{ + "base_script_file": "vpcs_base_config.txt", + "builtin": false, + "category": "guest", + "compute_id": "local", + "console_auto_start": false, + "console_type": "telnet", + "default_name_format": "PC{0}", + "name": "VPCS_TEST", + "symbol": ":/symbols/vpcs_guest.svg", + "template_id": "7f121fee-44da-4842-8faf-adf17159ffbd", + "template_type": "vpcs" +} diff --git a/docs/api/examples/controller_put_templatestemplateid.txt b/docs/api/examples/controller_put_templatestemplateid.txt new file mode 100644 index 00000000..8a63ebf6 --- /dev/null +++ b/docs/api/examples/controller_put_templatestemplateid.txt @@ -0,0 +1,38 @@ +curl -i -X PUT 'http://localhost:3080/v2/templates/31263538-d569-4138-89f8-68612d04edb8' -d '{"base_script_file": "vpcs_base_config.txt", "category": "guest", "compute_id": "local", "console_auto_start": false, "console_type": "telnet", "default_name_format": "PC{0}", "name": "VPCS_TEST_RENAMED", "symbol": ":/symbols/vpcs_guest.svg", "template_id": "31263538-d569-4138-89f8-68612d04edb8", "template_type": "vpcs"}' + +PUT /v2/templates/31263538-d569-4138-89f8-68612d04edb8 HTTP/1.1 +{ + "base_script_file": "vpcs_base_config.txt", + "category": "guest", + "compute_id": "local", + "console_auto_start": false, + "console_type": "telnet", + "default_name_format": "PC{0}", + "name": "VPCS_TEST_RENAMED", + "symbol": ":/symbols/vpcs_guest.svg", + "template_id": "31263538-d569-4138-89f8-68612d04edb8", + "template_type": "vpcs" +} + + +HTTP/1.1 200 +Connection: close +Content-Length: 386 +Content-Type: application/json +Date: Tue, 27 Nov 2018 15:09:55 GMT +Server: Python/3.6 GNS3/2.2.0dev5 +X-Route: /v2/templates/{template_id} + +{ + "base_script_file": "vpcs_base_config.txt", + "builtin": false, + "category": "guest", + "compute_id": "local", + "console_auto_start": false, + "console_type": "telnet", + "default_name_format": "PC{0}", + "name": "VPCS_TEST_RENAMED", + "symbol": ":/symbols/vpcs_guest.svg", + "template_id": "31263538-d569-4138-89f8-68612d04edb8", + "template_type": "vpcs" +} diff --git a/docs/api/v2/controller/template.rst b/docs/api/v2/controller/template.rst new file mode 100644 index 00000000..0c4b1ec7 --- /dev/null +++ b/docs/api/v2/controller/template.rst @@ -0,0 +1,8 @@ +Template +----------------------------- + +.. toctree:: + :glob: + :maxdepth: 2 + + template/* diff --git a/docs/api/v2/controller/template/projectsprojectidtemplatestemplateid.rst b/docs/api/v2/controller/template/projectsprojectidtemplatestemplateid.rst new file mode 100644 index 00000000..cc084409 --- /dev/null +++ b/docs/api/v2/controller/template/projectsprojectidtemplatestemplateid.rst @@ -0,0 +1,64 @@ +/v2/projects/{project_id}/templates/{template_id} +------------------------------------------------------------------------------------------------------------------------------------------ + +.. contents:: + +POST /v2/projects/**{project_id}**/templates/**{template_id}** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Create a node from a template + +Parameters +********** +- **project_id**: Project UUID +- **template_id**: Template UUID + +Response status codes +********************** +- **201**: Node created +- **404**: The project or template doesn't exist + +Input +******* +.. raw:: html + + + + + + +
Name Mandatory Type Description
compute_id ['null', 'string'] If the template don't have a default compute use this compute
x ✔ integer X position
y ✔ integer Y position
+ +Output +******* +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Name Mandatory Type Description
command_line ['null', 'string'] Command line use to start the node
compute_id ✔ string Compute identifier
console ['integer', 'null'] Console TCP port
console_auto_start boolean Automatically start the console when the node has started
console_host string Console host. Warning if the host is 0.0.0.0 or :: (listen on all interfaces) you need to use the same address you use to connect to the controller.
console_type enum Possible values: vnc, telnet, http, https, spice, spice+agent, none, null
custom_adapters array
first_port_name ['string', 'null'] Name of the first port
height integer Height of the node (Read only)
label object
name ✔ string Node name
node_directory ['null', 'string'] Working directory of the node. Read only
node_id string Node UUID
node_type ✔ enum Possible values: cloud, nat, ethernet_hub, ethernet_switch, frame_relay_switch, atm_switch, docker, dynamips, vpcs, traceng, virtualbox, vmware, iou, qemu
port_name_format string Formating for port name {0} will be replace by port number
port_segment_size integer Size of the port segment
ports array List of node ports READ only
project_id string Project UUID
properties object Properties specific to an emulator
status enum Possible values: stopped, started, suspended
symbol ['string', 'null'] Symbol of the node
template_id ['null', 'string'] Template UUID from which the node has been created. Read only
width integer Width of the node (Read only)
x integer X position of the node
y integer Y position of the node
z integer Z position of the node
+ diff --git a/docs/api/v2/controller/template/templates.rst b/docs/api/v2/controller/template/templates.rst new file mode 100644 index 00000000..2495fa74 --- /dev/null +++ b/docs/api/v2/controller/template/templates.rst @@ -0,0 +1,67 @@ +/v2/templates +------------------------------------------------------------------------------------------------------------------------------------------ + +.. contents:: + +POST /v2/templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Create a new template + +Response status codes +********************** +- **201**: Template created +- **400**: Invalid request + +Input +******* +.. raw:: html + + + + + + + + + + + +
Name Mandatory Type Description
builtin boolean Template is builtin
category Template category
compute_id ✔ string Compute identifier
default_name_format string Default name format
name ✔ string Template name
symbol string Symbol of the template
template_id string Template UUID
template_type ✔ enum Possible values: cloud, ethernet_hub, ethernet_switch, docker, dynamips, vpcs, traceng, virtualbox, vmware, iou, qemu
+ +Output +******* +.. raw:: html + + + + + + + + + + + +
Name Mandatory Type Description
builtin ✔ boolean Template is builtin
category ✔ Template category
compute_id ✔ string Compute identifier
default_name_format ✔ string Default name format
name ✔ string Template name
symbol ✔ string Symbol of the template
template_id ✔ string Template UUID
template_type ✔ enum Possible values: cloud, ethernet_hub, ethernet_switch, docker, dynamips, vpcs, traceng, virtualbox, vmware, iou, qemu
+ +Sample session +*************** + + +.. literalinclude:: ../../../examples/controller_post_templates.txt + + +GET /v2/templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +List of template + +Response status codes +********************** +- **200**: Template list returned + +Sample session +*************** + + +.. literalinclude:: ../../../examples/controller_get_templates.txt + diff --git a/docs/api/v2/controller/template/templatestemplateid.rst b/docs/api/v2/controller/template/templatestemplateid.rst new file mode 100644 index 00000000..37a35d08 --- /dev/null +++ b/docs/api/v2/controller/template/templatestemplateid.rst @@ -0,0 +1,107 @@ +/v2/templates/{template_id} +------------------------------------------------------------------------------------------------------------------------------------------ + +.. contents:: + +GET /v2/templates/**{template_id}** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Get an template + +Response status codes +********************** +- **200**: Template found +- **400**: Invalid request +- **404**: Template doesn't exist + +Output +******* +.. raw:: html + + + + + + + + + + + +
Name Mandatory Type Description
builtin ✔ boolean Template is builtin
category ✔ Template category
compute_id ✔ string Compute identifier
default_name_format ✔ string Default name format
name ✔ string Template name
symbol ✔ string Symbol of the template
template_id ✔ string Template UUID
template_type ✔ enum Possible values: cloud, ethernet_hub, ethernet_switch, docker, dynamips, vpcs, traceng, virtualbox, vmware, iou, qemu
+ +Sample session +*************** + + +.. literalinclude:: ../../../examples/controller_get_templatestemplateid.txt + + +PUT /v2/templates/**{template_id}** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Update an template + +Response status codes +********************** +- **200**: Template updated +- **400**: Invalid request +- **404**: Template doesn't exist + +Input +******* +.. raw:: html + + + + + + + + + + + +
Name Mandatory Type Description
builtin boolean Template is builtin
category Template category
compute_id string Compute identifier
default_name_format string Default name format
name string Template name
symbol string Symbol of the template
template_id string Template UUID
template_type enum Possible values: cloud, ethernet_hub, ethernet_switch, docker, dynamips, vpcs, traceng, virtualbox, vmware, iou, qemu
+ +Output +******* +.. raw:: html + + + + + + + + + + + +
Name Mandatory Type Description
builtin ✔ boolean Template is builtin
category ✔ Template category
compute_id ✔ string Compute identifier
default_name_format ✔ string Default name format
name ✔ string Template name
symbol ✔ string Symbol of the template
template_id ✔ string Template UUID
template_type ✔ enum Possible values: cloud, ethernet_hub, ethernet_switch, docker, dynamips, vpcs, traceng, virtualbox, vmware, iou, qemu
+ +Sample session +*************** + + +.. literalinclude:: ../../../examples/controller_put_templatestemplateid.txt + + +DELETE /v2/templates/**{template_id}** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Delete an template + +Parameters +********** +- **template_id**: template UUID + +Response status codes +********************** +- **204**: Template deleted +- **400**: Invalid request +- **404**: Template doesn't exist + +Sample session +*************** + + +.. literalinclude:: ../../../examples/controller_delete_templatestemplateid.txt + diff --git a/docs/api/v2/controller/template/templatestemplateidduplicate.rst b/docs/api/v2/controller/template/templatestemplateidduplicate.rst new file mode 100644 index 00000000..6f66c345 --- /dev/null +++ b/docs/api/v2/controller/template/templatestemplateidduplicate.rst @@ -0,0 +1,41 @@ +/v2/templates/{template_id}/duplicate +------------------------------------------------------------------------------------------------------------------------------------------ + +.. contents:: + +POST /v2/templates/**{template_id}**/duplicate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Duplicate an template + +Parameters +********** +- **template_id**: Template UUID + +Response status codes +********************** +- **201**: Template duplicated +- **400**: Invalid request +- **404**: Template doesn't exist + +Output +******* +.. raw:: html + + + + + + + + + + + +
Name Mandatory Type Description
builtin ✔ boolean Template is builtin
category ✔ Template category
compute_id ✔ string Compute identifier
default_name_format ✔ string Default name format
name ✔ string Template name
symbol ✔ string Symbol of the template
template_id ✔ string Template UUID
template_type ✔ enum Possible values: cloud, ethernet_hub, ethernet_switch, docker, dynamips, vpcs, traceng, virtualbox, vmware, iou, qemu
+ +Sample session +*************** + + +.. literalinclude:: ../../../examples/controller_post_templatestemplateidduplicate.txt +