List Virtual Switches of a CPC

The List Virtual Switches of a CPC operation lists virtual switches that are defined to the CPC.

HTTP method and URI

GET /api/cpcs/{cpc-id}/virtual-switches

In this request, the URI variable {cpc-id} is the object ID of the CPC for which virtual switches are to be listed.

Query parameters:

Name Type Rqd/Opt Description
name String Optional Filter pattern (regular expression) to limit returned objects to those objects that have a matching name property
type String Enum Optional Filter string to limit returned objects to those objects that have a matching type property. The value must be a valid type property value.
additional-properties List of String Enum Optional A list of properties to be included in the response in addition to the default properties (name, object-uri, type). This is a list of comma-separated strings where each string is a property name defined in the Virtual Switch object's data model.

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description
virtual-switches Array of objects Array of nested virtual-switch-info objects as described in the next table.

Each nested virtual-switch-info object contains the following fields:

Field name Type Description
object-uri String/ URI The object-uri property of the Virtual Switch object.
name String The name property of the Virtual Switch object
type String Enum The type property of the Virtual Switch object

Description

This operation lists Virtual Switches defined to the CPC. Some basic properties are provided for each virtual switch that is included in the response.

If the request URI does not identify a CPC object to which the API user has object-access permission, HTTP status code 404 (Not Found) is returned.

If the name query parameter is specified, the returned list is limited to those virtual switches that have a name property matching the specified filter pattern. If the name parameter is omitted, no such filtering is performed.

If the type query parameter is specified, the parameter is validated to ensure that it is a valid virtual switch type property value. If the value is not valid, HTTP status code 400 (Bad Request) is returned. If the value is valid, the returned list is limited to those virtual switches that have a type property matching the specified value. If the type parameter is omitted, no such filtering is performed.

If the additional-properties query parameter is specified, the response body is enhanced with the additionally requested properties. The presence and value of each requested property is the same as it would be in the response body of a Get Virtual Switch Properties operation. That is, it may be omitted or contain a special value, such as null, -1, or an empty string, if a prerequisite condition is not met. If the additional-properties query parameter is omitted, only the default properties are included in the response.

A virtual switch is included in the list only if the API user has object-access permission to the backing adapter of that virtual switch. If there is a virtual switch to which the API user does not have permission, that object is omitted from the list, but no error status code results.

If the CPC is not in DPM mode, or there are no virtual switches defined to the CPC, or no virtual switches are to be included in the response due to filtering or access permissions, an empty list is provided and the operation completes successfully.

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the CPC object identified in the request URI
  • Object-access permission to the backing adapter of the Virtual Switch objects to be included in the response body.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in Response body contents.

Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body providing the reason code indicated and associated error message.

HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
404 (Not Found) 1 The request URI does not designate an existing resource of the expected type, or it designates a resource for which the API user does not have object-access permission.
409 (Conflict) 329 The operation cannot be performed because the CPC designated by the request URI is an unmanaged CPC, which is not supported by this operation.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. List Virtual Switches of a CPC: Request
GET /api/cpcs/8e543aa6-1c26-3544-8197-4400110ef5ef/virtual-switches
x-api-session: 1jgbldxyy2inf0p7aaj9a8p87j7awxsr1mstmfnw07hvoaz8da
Figure 2. List Virtual Switches of a CPC: Response
200 OK
server: zSeries management console API web server / 2.0
cache-control:no-cache
date: Tue, 31 Mar 2015 06:20:54 GMT
content-type: application/json;charset=UTF-8
content-length: 255
{
  "virtual-switches":[
  {
   "name":"PrimeIQDVSwitch1",
   "object-uri":"/api/virtual-switches/f6b4c70e-d491-11e4-a555-020000003058",
   "type":"hipersockets"
  },
  {
   "name":"5F1.P0.OSD",
   "object-uri":"/api/virtual-switches/dff0b71c-d491-11e4-a555-020000003058",
   "type":"osd"
  }
 ]
}