Virtual serial number (VSN) APIs

Edit online

The virtual serial number (VSN) APIs that are used in the VSN feature are listed in this topic.

Virtual serial number APIs

The table lists API options for VSN.
Table 1. API options for VSN
Method API Description
GET /v2.1/{tenant_id}/virtual-serial-number

/v2.1/{tenant_id}/virtual-serial-number?host=<HOST_MTMS>

 Provides details about the reserved VSNs and the associated host and description.

The supported host parameter accepts the host Machine Type Machine Serial (MTMS) as a value and filters the reserved VSNs with the specified host MTMS value.
PUT /v2.1/{tenant_id}/virtual-serial-number?action=move Moves the list of VSNs from a specific source host to the specified target host.

Listed are the parameters in the request body.

  • move_vsns (body, string): Specifies the action. Transfer or move VSNs from source host to destination host.
  • source_host (body, string): The source host MTMS.
  • target_host (body, string): The target host MTMS.
  • vsns (body, string): The list of VSNs to be transferred.
POST /v2.1/{tenant_id}/virtual-serial-number?action=reserve This API enables users to reserve a VSN in the current project. This capability is only supported on NovaLink managed hosts.
POST /v2.1/{tenant_id}/virtual-serial-number?action=unreserve This API enables users to unreserve a VSN, and the VSN is released back to the host. This capability is supported only on NovaLink managed hosts.
POST /v2.1/{tenant_id}/virtual-serial-number?action=update_reservation This API is used to update the description of a reserved VSN. This capability is only supported on NovaLink managed hosts.

VSN move API

Response codes
  • Normal response code: Accepted (202)
  • Error response codes: Bad Request (400), Forbidden (403), Unauthorized (401), Not Found (404), Server Error (500)
Example of request body
{ 
    “move_vsns”: { 
     “source_host”: “<MTMS>”, 
     “target_host”: “<MTMS>”, 
     "vsns”: [“CDF0003”, “CDF0002”]
}

VSN reserve API

Response codes
  • Normal response code: OK (200)
Example of request body
{
    “virtual_serial_number”: “ABCD567”,
    “description” : “Sample description”
}

VSN unreserve API

Response codes
  • Normal response code: OK (200)
Example of request body
{
          “virtual_serial_number”:  “ABCD001”
}

VSN update reservation API

Response codes
  • Normal response code: OK (200)
Example of request body
{
    “virtual_serial_number”: “ABCD567”,
    “description” : “updated description”
}

VSN Server APIs

The table lists API options for VSN server APIs

Table 2. API options for VSN server APIs
Method API Description
POST /v2.1/{tenant_id}/servers Creates a VM. Specify powervm:virtual_serial_number in flavor.extra_specs for creating the VM with the VSN identified by its value in the request body.

Parameter in the request body includes powervm:virtual_serial_number": "<Valid Value>": The valid values are 'auto', 'none', or a valid VSN with a 7-character alpha-numeric value such as ABCD007.

GET /v2.1/{tenant_id}/servers Lists IDs, names, and links for all servers. The response also includes the VSN for each VM. If the VM does not have a VSN or existing VMs (without VSN), the response returns 'none' for VSN.
POST /v2.1/{tenant_id}/servers/{server_id}/action Assigns a VSN to the specified server. Specify assign_vsn action in the request body with virtual_serial_number parameter set to 'auto' or a valid VSN.

Listed are the parameters in the request body.

  • assign_vsn (body, string): Specifies the assign VSN action.
  • virtual_serial_number (body, string): 'auto' or a valid VSN with a 7-character alpha-numeric value such as ABCD007.
POST /v2.1/{tenant_id}/servers/{server_id}/action Unassigns a VSN from the specified server.
Example of request body for assign_vsn
{ 
     "assign_vsn": { "virtual_serial_number": "auto" or "ABCDEFG" } 
}
Example of request body for unassign_vsn
{ 
    “unassign_vsn”:  null 
}

References