#
# Copyright (c) 2015-2016 Wind River Systems, Inc.
#
# SPDX-License-Identifier: Apache-2.0
#
---
page_title: Software Image Management
page_description: >
  These interfaces allows an authorized consumer functional block to manage
  the VNF software images in the VIM.

query_response: &alias_query_response
  - name: uuid
    type: xsd:string
    description: UUID of the image.
  - name: name
    type: xsd:string
    description: Name of the image.
  - name: description
    type: xsd:string
    description: >
      Description of the image. Defaults to the empty string.
  - name: container_format
    type: xsd:string
    description: >
      Format of container.  One of ami, ari, aki, bare, ovf, ova.
  - name: disk_format
    type: xsd:string
    description: >
      Format of disk.  One of ami, ari, aki, vhd, vmdk, raw, qcow2, vdi,
      iso.
  - name: minimum_disk_size
    type: xsd:string
    description: Minimum size of disk in GB.
  - name: minimum_memory_size
    type: xsd:string
    description: Minimum size of memory in MB.
  - name: visibility
    type: xsd:string
    description: >
      Visibility of the image.  One of private, public, shared.
  - name: protected
    type: xsd:string
    description: Determines if image is deletable.
  - name: availability_status
    type: xsd:string
    description: Status of the image.
  - name: action
    type: xsd:string
    description: Current action being performed on the image.

api_group_images: &alias_api_group_images
  name: Images
  api_listing:
    - id: add_image
      name: Add Image
      description: Allows adding a new software image to the image repository.
      method: POST
      urls:
        - /v1/images
      request:
        - name: name
          optional: "no"
          type: xsd:string
          description: Name of the image.
        - name: description
          optional: "yes"
          type: xsd:string
          description: >
            Description of the image. Defaults to the empty string.
        - name: container_format
          optional: "no"
          type: xsd:string
          description: >
            Format of container.  One of ami, ari, aki, bare, ovf, ova.
        - name: disk_format
          optional: "no"
          type: xsd:string
          description: >
            Format of disk.  One of ami, ari, aki, vhd, vmdk, raw, qcow2, vdi,
            iso.
        - name: minimum_disk_size
          optional: "yes"
          type: xsd:string
          description: Minimum size of disk in GB. Defaults to no minimum.
        - name: minimum_memory_size
          optional: "yes"
          type: xsd:string
          description: Minimum size of memory in MB. Defaults to no minimum.
        - name: visibility
          optional: "yes"
          type: xsd:string
          description: >
            Visibility of the image.  One of private, public, shared. Defaults
            to 'public'.
        - name: protected
          optional: "yes"
          type: xsd:boolean
          description: Determines if image is deletable. Defaults to 'no'.
        - name: properties
          optional: "yes"
          type: xsd:string
          description: List of properties to be associated with the image.
        - name: image_data_ref
          optional: "no"
          type: xsd:string
          description: >
            URL of where the image data is located.  URL can be located on the
            local disk (URL starts with file://) or located on a HTTP server
            (URL starts with http://).
      response: *alias_query_response
      normal_codes:
        - name: Created
          value: 201
      error_codes:
        - name: Bad Request
          value: 400
        - name: Internal Server Error
          value: 500
      examples:
        - title: Add a software image where the image data is on local disk
          description: >
            This example demonstrates how to add a software image where the
            image data is on the local disk to the image repository using curl
            commands.
          request: >
            curl -i -X POST -H 'Content-Type: application/json'
            -H 'Accept: application/json'
            http://localhost:4545/v1/images
            -d "{\"name\": \"cirros\", \"container_format\": \"bare\",
            \"disk_format\": \"qcow2\",  \"image_data_ref\":
            \"file://scratch/cirros-0.3.0-x86_64-disk.img\"}"
          response: >
            {"description": "", "container_format": "bare",
            "disk_format": "qcow2", "minimum_disk_size": 0,
            "visibility": "public", "name": "cirros", "protected": "no",
            "availability_status": ["available"], "action": "",
            "minimum_memory_size": 0,
            "uuid": "9a770e3f-e67d-482d-b592-092226fdd119"}
        - title: Add a software image where the image data is on a HTTP server
          description: >
            This example demonstrates how to add a software image where the
            image data is on a remote http server to the image repository using
            curl commands.
          request: >
            curl -i -X POST -H 'Content-Type: application/json'
            -H 'Accept: application/json' http://localhost:4545/v1/images
            -d "{\"name\": \"cirros\", \"container_format\": \"bare\",
            \"disk_format\": \"qcow2\",  \"image_data_ref\":
            \"http://192.168.204.15:4545/file/cirros-0.3.0-x86_64-disk.img\"}"
          response: >
            {"description": "", "container_format": "bare",
            "disk_format": "qcow2", "minimum_disk_size": 0,
            "visibility": "public", "name": "cirros",
            "protected": "no", "availability_status": ["available"],
            "action": "", "minimum_memory_size": 0,
            "uuid": "4ebfeb7c-c783-4c2d-a1cd-1558f06c6dba"}

    - id: update_image
      name: Update Image
      description: Allows updating a software image in the image repository.
      method: PUT
      urls:
        - /v1/images/{image_uuid}
      request:
        - name: description
          optional: "yes"
          type: xsd:string
          description: >
            Description of the image.
        - name: minimum_disk_size
          optional: "yes"
          type: xsd:string
          description: Minimum size of disk in GB.
        - name: minimum_memory_size
          optional: "yes"
          type: xsd:string
          description: Minimum size of memory in MB.
        - name: visibility
          optional: "yes"
          type: xsd:string
          description: >
            Visibility of the image.  One of private, public, shared.
        - name: protected
          optional: "yes"
          type: xsd:boolean
          description: Determines if image is deletable.
      response: *alias_query_response
      normal_codes:
        - name: Okay
          value: 200
      error_codes:
        - name: Bad Request
          value: 400
        - name: Not Found
          value: 404
        - name: Internal Server Error
          value: 500
      examples:
        - title: Update a software image
          description: >
            This example demonstrates how to update attributes of a software
            image in the image repository using curl commands.
          request: >
            curl -i -X PUT -H 'Content-Type: application/json'
            -H 'Accept: application/json'
            http://localhost:4545/v1/images/9a770e3f-e67d-482d-b592-092226fdd119
            -d "{\"description\": \"new cirros image\",
            \"minimum_disk_size\": \"1\",  \"minimum_memory_size\": \"512\",
            \"visibility\": \"private\", \"protected\": false}"
          response: >
            {"description": "new cirros image", "container_format": "bare",
            "disk_format": "qcow2", "minimum_disk_size": 1,
            "visibility": "private", "name": "cirros", "protected": "yes",
            "availability_status": ["available"], "action": "",
            "minimum_memory_size": 512,
            "uuid": "9a770e3f-e67d-482d-b592-092226fdd119"}

    - id: delete_image
      name: Delete Image
      description: Allows deleting a software image from the image repository.
      method: DELETE
      urls:
        - /v1/images/{image_uuid}
      normal_codes:
        - name: No Content
          value: 204
      error_codes:
        - name: Bad Request
          value: 400
        - name: Not Found
          value: 404
        - name: Internal Server Error
          value: 500
      examples:
        - title: Delete a software image
          description: >
            This example demonstrates how to delete a particular software image
            from the image repository using curl commands.
          request: >
            curl -i -X DELETE -H 'Content-Type: application/json'
            -H 'Accept: application/json'
            http://localhost:4545/v1/images/9a770e3f-e67d-482d-b592-092226fdd119
          response: >
            No response is returned.

    - id: query_images
      name: Query Image(s)
      description: >
        Allows querying the information of all the software images or a single
        software image from the image repository.
      method: GET
      urls:
        - /v1/images
        - /v1/images/{image_uuid}
      response: *alias_query_response
      normal_codes:
        - name: Okay
          value: 200
      error_codes:
        - name: Not Found
          value: 404
        - name: Internal Server Error
          value: 500
      examples:
        - title: Query all software images
          description: >
            This example demonstrates how to query all software images from the
            image repository using curl commands.
          request: >
            curl -i -X GET -H 'Content-Type: application/json'
            -H 'Accept: application/json' http://localhost:4545/v1/images
          response: >
            [{"description": "new cirros image", "container_format": "bare",
            "disk_format": "qcow2", "minimum_disk_size": 1,
            "visibility": "private", "name": "cirros", "protected": "yes",
            "availability_status": ["available"], "action": "",
            "minimum_memory_size": 512,
            "uuid": "9a770e3f-e67d-482d-b592-092226fdd119"},
            {"description": "", "container_format": "bare",
            "disk_format": "qcow2", "minimum_disk_size": 1,
            "visibility": "public", "name": "vim-test-image", "protected": "no",
            "availability_status": ["available"], "action": "",
            "minimum_memory_size": 512,
            "uuid": "def2d2c8-7411-45a0-a9e1-fc343c641b07"}]
        - title: Query a software image
          description: >
            This example demonstrates how to query a particular software image
            from the image repository using curl commands.
          request: >
            curl -i -X GET -H 'Content-Type: application/json'
            -H 'Accept: application/json'
            http://localhost:4545/v1/images/def2d2c8-7411-45a0-a9e1-fc343c641b07
          response: >
            {"description": "", "container_format": "bare",
            "disk_format": "qcow2", "minimum_disk_size": 1,
            "visibility": "public", "name": "vim-test-image",
            "protected": "no", "availability_status": ["available"],
            "action": "", "minimum_memory_size": 512,
            "uuid": "def2d2c8-7411-45a0-a9e1-fc343c641b07"}

api_group_list:
  - *alias_api_group_images