#
# Copyright (c) 2015-2016 Wind River Systems, Inc.
#
# SPDX-License-Identifier: Apache-2.0
#
---
page_title: Virtualised Network Resource
page_description: >
  These interfaces allows an authorized consumer functional block to manage
  virtualized network resources in the VIM.

api_networks: &api_networks_grouping
  name: Networks
  data_model: network_model.svg
  api_listing:
    - id: allocate_network
      name: Allocate Network
      description: Allows for the instantiation and assignment of a network.
      method: POST
      urls:
        - /v1/virtualised_resources/networks
      request:
        - name: network_resource_id
          optional: "no"
          type: string
          description: Name of the network.
        - name: reservation_id
          optional: "yes"
          type: string
          description: Unique identifier representing a resource reservation.
        - name: network_resource_type
          optional: "no"
          type: string
          description: >
            Type of virtualised network resource being allocated. One of
            network, subnet.
        - name: type_network_data
          optional: "yes"
          type: NetworkType
          description: >
            The network data about the particular network resource to create.
        - name: type_subnet_data
          optional: "yes"
          type: NetworkSubnetType
          description: >
            The subnet data about the particular sub-network resource to
            create.
        - name: meta_data
          optional: "yes"
          type: key-value pairs
          description: List of key-value pairs.
      response:
        - name: operation_result
          type: string
          description: Result of the request, indicating pass or failed.
        - name: network_data
          type: NetworkResourceType
          description: >
            The network data about the particular network resource that
            was created.
        - name: subnet_data
          type: NetworkSubnetResourceType
          description: >
            The subnet data about the particular sub-network resource that
            was created.
        - name: message
          type: string
          description: >
            Additional information about the allocation request result.
      normal_codes:
        - name: Created
          value: 201
      error_codes:
        - name: Bad Request
          value: 400
        - name: Internal Server Error
          value: 500
      examples:
        - title: Allocate a network
          description: >
            This example demonstrates how to allocate a network with subnets.
          request: >
            cat > network_ipv4_subnets_request.txt
             {"network_resource_id": "network-ipv4-subnets",
              "network_resource_type": "network",
              "type_network_data": {
                "type_of_network": "vlan",
                "type_of_segment": "351",
                "wrs_physical_network": "physnet-x",
                "is_shared": true,
                "layer3_attributes": [
                  {"ip_version": "4",
                   "is_dhcp_enabled": true,
                   "gateway_ip": "192.168.12.1",
                   "wrs_subnet_ip": "192.168.12.0",
                   "wrs_subnet_prefix": 24}
                ]}}

            curl -i -X POST -H 'Content-Type: application/json'
            -H 'Accept: application/json'
            http://localhost:4545/v1/virtualised_resources/networks
            -d @network_ipv4_subnets_request.txt
          response: >
            {"operation_result": null, "message": null,
             "network_data": {
               "network_attributes": {
                 "is_shared": true,
                 "type_of_network": "vlan",
                 "type_of_segment": "351",
                 "layer3_attributes": [
                   {"is_dhcp_enabled": true,
                    "meta_data": null,
                    "wrs_subnet_ip": "192.168.12.0",
                    "gateway_ip": "192.168.12.1",
                    "ip_version": "4",
                    "wrs_subnet_prefix": 24}
                 ],
               "sharing_criteria": null,
               "bandwidth": 0,
               "meta_data": null,
               "network_qos": []},
               "resource_id": "network-ipv4-subnets"}}

    - id: update_network
      name: Update Network
      description: Allows updating the information for a network.
      method: PATCH
      urls:
        - /v1/virtualised_resources/networks
      request:
        - name: network_resource_id
          optional: "no"
          type: string
          description: Name of the network.
        - name: update_network_data
          optional: "yes"
          type: NetworkType
          description: >
            The network data to use to update a particular network resource.
        - name: update_subnet_data
          optional: "yes"
          type: NetworkSubnetType
          description: >
            The subnet data to use to update a particular sub-network resource.
        - name: meta_data
          optional: "yes"
          type: key-value pairs
          description: List of key-value pairs.
      response:
        - name: operation_result
          type: string
          description: Result of the request, indicating pass or failed.
        - name: network_resource_id
          type: string
          description: Name of the network.
        - name: network_data
          type: NetworkResourceType
          description: >
            The network data about the particular network resource that
            was updated.
        - name: subnet_data
          type: NetworkSubnetResourceType
          description: >
            The subnet data about the particular sub-network resource that
            was updated.
        - name: message
          type: string
          description: Additional information about the update request result.
      normal_codes:
        - name: Okay
          value: 200
      error_codes:
        - name: Bad Request
          value: 400
        - name: Internal Server Error
          value: 500
      examples:
        - title: Update a network
          description: >
            This example demonstrates how to update a network with subnets.
          request: >
            cat > network_update_ipv4_ipv6_subnets_request.txt
             {"network_resource_id": "network-ipv4-subnets",
              "update_network_data": {
                "layer3_attributes": [
                  {"ip_version": "4",
                   "is_dhcp_enabled": true,
                   "wrs_subnet_ip": "192.168.14.0",
                   "wrs_subnet_prefix": "24"},
                  {"ip_version": "6",
                   "is_dhcp_enabled": false,
                   "gateway_ip": "3FFE::1",
                   "wrs_subnet_ip": "3FFE::",
                   "wrs_subnet_prefix": "16"},
                  {"ip_version": "4",
                   "is_dhcp_enabled": false,
                   "gateway_ip": "192.168.15.1",
                   "wrs_subnet_ip": "192.168.15.0",
                   "wrs_subnet_prefix": "24"}
                ]}}

            curl -i -X PATCH -H 'Content-Type: application/json'
            -H 'Accept: application/json'
            http://localhost:4545/v1/virtualised_resources/networks
            -d @network_update_ipv4_ipv6_subnets_request.txt
          response: >
            {"operation_result": null,
             "message": null,
             "network_data": {
               "network_attributes": %%{
                 "is_shared": false,
                 "type_of_network": "vlan",
                 "type_of_segment": "351",
                 "layer3_attributes": [
                   {"network_id": "143fab9e-b4d2-4239-867b-d52e254d6d86",
                    "is_dhcp_enabled": false,
                    "meta_data": null,
                    "wrs_subnet_ip": "192.168.15.0",
                    "gateway_ip": "192.168.15.1",
                    "ip_version": "4",
                    "wrs_subnet_prefix": 24},
                   {"network_id": "143fab9e-b4d2-4239-867b-d52e254d6d86",
                    "is_dhcp_enabled": false,
                    "meta_data": null,
                    "wrs_subnet_ip": "3ffe::",
                    "gateway_ip": "3FFE::1",
                    "ip_version": "6",
                    "wrs_subnet_prefix": 16},
                   {"network_id": "143fab9e-b4d2-4239-867b-d52e254d6d86",
                    "is_dhcp_enabled": true,
                    "meta_data": null,
                    "wrs_subnet_ip": "192.168.14.0",
                    "gateway_ip": "192.168.14.1",
                    "ip_version": "4",
                    "wrs_subnet_prefix": 24}
                 ],
                 "sharing_criteria": null,
                 "bandwidth": 0,
                 "meta_data": null,
                 "network_qos": []},
               "resource_id": "network-ipv4-subnets"}}

    - id: delete_network
      name: Delete Network
      description: Allows deleting a network.
      method: DELETE
      urls:
        - /v1/virtualised_resources/networks
      request:
        - name: network_resource_ids
          optional: "no"
          type: string list
          description: List of network resource identifiers to be deleted.
      response:
        - name: operation_result
          type: string
          description: Result of the request, indicating pass or failed.
        - name: network_resource_ids
          type: list of strings
          description: >
            List of network resource identifiers that have been deleted.
        - name: message
          type: string
          description: Additional information about the delete request result.
      normal_codes:
        - name: Okay
          value: 200
      error_codes:
        - name: Bad Request
          value: 400
        - name: Internal Server Error
          value: 500
      examples:
        - title: Delete a network
          description: >
            This example demonstrates how to delete a network.
          request: >
            cat > network_delete_request.txt
             {"network_resource_ids": ["network-ipv4-subnets"]}

            curl -i -X DELETE -H 'Content-Type: application/json'
            -H 'Accept: application/json'
            http://localhost:4545/v1/virtualised_resources/networks
            -d @network_delete_request.txt
          response: >
            {"operation_result": null, "network_resource_ids":
            ["network-ipv4-subnets"], "message": null}

    - id: get_network
      name: Get Network(s)
      description: >
        Allows querying the information of all the networks or a
        a single network.
      method: GET
      urls:
        - /v1/virtualised_resources/networks
        - /v1/virtualised_resources/networks/{resource_id}
      response:
        - name: operation_result
          type: string
          description: Result of the request, indicating pass or failed.
        - name: query_result
          type: NetworkResourceType(s)
          description: A list of network data that was request.
        - name: message
          type: string
          description: Additional information about the query request result.
      normal_codes:
        - name: Okay
          value: 200
      error_codes:
        - name: Bad Request
          value: 400
        - name: Internal Server Error
          value: 500
      examples:
        - title: Query a network
          description: >
            This example demonstrates how to query a network.
          request: >
            curl -i -X GET -H 'Content-Type: application/json'
            -H 'Accept: application/json'
            http://localhost:4545/v1/virtualised_resources/networks/network-ipv4-subnets
          response: >
            {"operation_result": null, "message": null,
             "query_result": [
               {"network_attributes": {
                 "is_shared": false,
                 "type_of_network": "vlan",
                 "type_of_segment": "351",
                 "layer3_attributes": [
                   {"network_id": "143fab9e-b4d2-4239-867b-d52e254d6d86",
                    "is_dhcp_enabled": false,
                    "meta_data": null,
                    "wrs_subnet_ip": "192.168.15.0",
                    "gateway_ip": "192.168.15.1",
                    "ip_version": "4",
                    "wrs_subnet_prefix": 24},
                   {"network_id": "143fab9e-b4d2-4239-867b-d52e254d6d86",
                    "is_dhcp_enabled": false,
                    "meta_data": null,
                    "wrs_subnet_ip": "3ffe::",
                    "gateway_ip": "3FFE::1",
                    "ip_version": "6",
                    "wrs_subnet_prefix": 16},
                   {"network_id": "143fab9e-b4d2-4239-867b-d52e254d6d86",
                    "is_dhcp_enabled": true,
                    "meta_data": null,
                    "wrs_subnet_ip": "192.168.14.0",
                    "gateway_ip": "192.168.14.1",
                    "ip_version": "4",
                    "wrs_subnet_prefix": 24}
                 ],
                 "sharing_criteria": null,
                 "bandwidth": 0,
                 "meta_data": null,
                 "network_qos": []},
                 "resource_id": "network-ipv4-subnets"}]}

api_group_list:
  - *api_networks_grouping