Network Device

This chapter describes the network-device resource, properties and operations.

Overview

The resource network-device represents a device for network communication. With this resource you can configure, unconfigure a network device. You can list all available network devices and get their properties.

Resource Properties

Name Type Read Only Description
self String/URI yes The URI of adding a network device
deviceIds Array of Strings yes device bus ids of the CCW devices constituting the network device of the HW resource for OSA/Hipersockets
deviceName String yes network device name for configured device, for unconfigured device this property will not be available
type Enume String yes network device type like OSA (QDIO), HiperSockets
chpid Integer yes Chpid on which device is located
port Integer no which port on the device is used
state Enum String yes represents the state of the device

Enum Values:

type

OSA (QDIO), HiperSockets, OSD_100, OSD_1000, OSD_10GIG

Note : When OSA devices are unconfigured state, the type is OSA (QDIO)
When OSA devices are in online or offline state, the type is OSD_100, OSD_1000, OSD_10GIG , depending on the bandwidth of card.

state

online, offline, unconfigured

Resource Operations

Retrieve a list of Network Devices

Use this operation to retrieve a list of Network Devices.

Authentication/Authorization

The caller must provide a API token, refer to Invoking API operations.

The user represented by the API token must have the following role:

Network

This operation is available from the following network(s):

HTTP Method and URI

GET /api/com.ibm.zaci.system/network-device
Query Parameters
Name Type Description
configured Integer which devices should be listed (configured = 1, unconfigured = 0)
type String devices of particular card type to be listed. type = "Hipersockets and type = "OSA" is supported.

If no query parameters are specified, all network devices are returned.

Request headers

For the list of required headers, refer to the Invoking API operations section.

The following sections describe the acceptable values for certain headers.

Accept media types

Request message body

None

Response

An HTTP status code of 200 indicates a successful operation. The response message body contains data formatted as requested in the Accept header, with kind=collection. The instances array contains zero or more objects, as described under the Resource Properties topic.

Any other HTTP status code indicates a failed operation. Refer to Common request validation reason codes for a list of common HTTP status codes and associated IBM Secure Service Container for IBM Cloud Private System API reason codes. The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

Example: retrieve all devices

Request

GET /api/com.ibm.zaci.system/network-device HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response

HTTP/1.1 200 OK\r\n
header: Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
header: Content-Length: 12099
header: Connection: keep-alive
header: Zaci-Api: com.ibm.zaci.system/1.0
header: Server: z Software Test Appliance/1.1
header: Allow: DELETE, GET, HEAD, PUT
header: Cache-Control: private, max-age=0, no-cache
header: Date: Thu, 27 Oct 2016 04:51:11 GMT
header: Strict-Transport-Security: max-age=31536000; includeSubDomains
{u'instances': [{u'chpid': u'A8',
                 u'deviceIds': [u'0.0.1a80', u'0.0.1a81', u'0.0.1a82'],
                 u'deviceName': u'enccw0.0.1a80',
                 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.1a80',
                 u'state': u'online',
                 u'port': 0,
                 u'type': u'OSD_10GIG'},
                {u'chpid': u'FB',
                 u'deviceIds': [u'0.0.fb8c', u'0.0.fb8d', u'0.0.fb8e'],
                 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.fb8c',
                 u'state': u'unconfigured',
                 u'port': 0,
                 u'type': u'HiperSockets'}],
 u'kind': u'collection',
 u'resource-name': u'network-device',
 u'resource-version': u'1.0',
 u'self': u'/api/com.ibm.zaci.system/network-device'}

Example: retrieve unconfigured devices

Request

GET /api/com.ibm.zaci.system/network-device?configured=0 HTTP/1.1
Host: localhost
Accept-Encoding: identity
zACI-API: 1.0
Accept: application/vnd.ibm.zaci.payload+json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.

Response

HTTP/1.1 200 OK\r\n
header: Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
header: Content-Length: 11696
header: Connection: keep-alive
header: Zaci-Api: com.ibm.zaci.system/1.0
header: Server: z Software Test Appliance/1.1
header: Allow: DELETE, GET, HEAD, PUT
header: Cache-Control: private, max-age=0, no-cache
header: Date: Thu, 27 Oct 2016 04:51:08 GMT
header: Strict-Transport-Security: max-age=31536000; includeSubDomains
{u'instances': [{u'chpid': u'00',
                 u'deviceIds': [u'0.0.1000', u'0.0.1001', u'0.0.1002'],
                 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.1000',
                 u'state': u'unconfigured',
                 u'port': 0,
                 u'type': u'OSA (QDIO)'},
                {u'chpid': u'FB',
                 u'deviceIds': [u'0.0.fb8c', u'0.0.fb8d', u'0.0.fb8e'],
                 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.fb8c',
                 u'state': u'unconfigured',
                 u'port': 0,
                 u'type': u'HiperSockets'}],
 u'kind': u'collection',
 u'resource-name': u'network-device',
 u'resource-version': u'1.0',
 u'self': u'/api/com.ibm.zaci.system/network-device'}

Example: retrieve devices of type "OSA"

Request

GET /api/com.ibm.zaci.system/network-device?type=OSA HTTP/1.1
Host: localhost
Accept-Encoding: identity
zACI-API: 1.0
Accept: application/vnd.ibm.zaci.payload+json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.

Response

HTTP/1.1 200 OK\r\n
header: Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
header: Content-Length: 11696
header: Connection: keep-alive
header: Zaci-Api: com.ibm.zaci.system/1.0
header: Server: z Software Test Appliance/1.1
header: Allow: DELETE, GET, HEAD, PUT
header: Cache-Control: private, max-age=0, no-cache
header: Date: Thu, 27 Oct 2016 04:51:08 GMT
header: Strict-Transport-Security: max-age=31536000; includeSubDomains
{u'instances': [{u'chpid': u'00',
                 u'deviceIds': [u'0.0.1000', u'0.0.1001', u'0.0.1002'],
                 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.1000',
                 u'state': u'unconfigured',
                 u'port': 0,
                 u'type': u'OSA (QDIO)'},
                {u'chpid': u'FB',
                 u'deviceIds': [u'0.0.fb8c', u'0.0.fb8d', u'0.0.fb8e'],
                 u'deviceName': u'enccw0.0.fb8c',
                 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.fb8c',
                 u'state': u'offline',
                 u'port': 0,
                 u'type': u'OSD_100'},
                {u'chpid': u'C4',
                 u'deviceIds': [u'0.0.1810', u'0.0.1811', u'0.0.1812'],
                 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.1810',
                 u'state': u'online',
                 u'port': 1,
                 u'type': u'OSD_1000'},
                {u'chpid': u'A8',
                 u'deviceIds': [u'0.0.1a80', u'0.0.1a81', u'0.0.1a82'],
                 u'deviceName': u'enccw0.0.1a80',
                 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.1a80',
                 u'state': u'online',
                 u'port': 0,
                 u'type': u'OSD_10GIG'}],
 u'kind': u'collection',
 u'resource-name': u'network-device',
 u'resource-version': u'1.0',
 u'self': u'/api/com.ibm.zaci.system/network-device'}

Retrieve a Network Device

Use this operation to retrieve information about a specific Network Device.

Authentication/Authorization

The caller must provide a API token, refer to Invoking API operations.

The user represented by the API token must have the following role:

Network

This operation is available from the following network(s):

HTTP Method and URI
GET /api/com.ibm.zaci.system/network-device/deviceId

In this request, the URI variable deviceId is the Network Device identifier, the first device bus id from the deviceIds. The URI is obtained via the Retrieve a list of Network Devices operation.

Query Parameters

None

Request headers

For the list of required headers, refer to the Invoking API operations section.

The following sections describe the acceptable values for certain headers.

Accept media types

Request message body

None

Response

An HTTP status code of 200 indicates a successful operation. The response message body contains data formatted as requested in the Accept header, with kind=instance. The properties object is described under the Resource Properties topic.

Any other HTTP status code indicates a failed operation. Refer to Common request validation reason codes for a list of common HTTP status codes and associated IBM Secure Service Container for IBM Cloud Private System API reason codes. The response message body contains a application/vnd.ibm.zaci.payload+json media type object, with kind=error. The failure object contains additional details, as described under the Error responses topic.

Example

Request

GET /api/com.ibm.zaci.system/network-device/0.0.fb8c HTTP/1.1
Host: 9.9.9.9:443
Authorization: Bearer qwert.asdfg.zxcvb
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Response 

HTTP/1.1 200 OK\r\n
header: Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0
header: Content-Length: 336
header: Connection: keep-alive
header: Zaci-Api: com.ibm.zaci.system/1.0
header: Server: z Software Test Appliance/1.1
header: Allow: DELETE, GET, HEAD, PUT
header: Cache-Control: private, max-age=0, no-cache
header: Date: Thu, 27 Oct 2016 05:06:03 GMT
header: Strict-Transport-Security: max-age=31536000; includeSubDomains
{u'kind': u'instance',
 u'properties': {u'chpid': u'FB',
                 u'deviceIds': [u'0.0.fb8c', u'0.0.fb8d', u'0.0.fb8e'],
                 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.fb8c',
                 u'state': u'unconfigured',
                 u'port': 0,
                 u'type': u'HiperSockets'},
 u'resource-name': u'network-device',
 u'resource-version': u'1.0',
 u'self': u'/api/com.ibm.zaci.system/network-device/0.0.fb8c'}