List IO Elements

Edit online

The List IO Elements operation lists the IO Elements for the associated CPC object. [Added by feature io-element]

HTTP method and URI

GET /api/cpcs/{cpc-id}/io-elements

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Query parameters:
Table 1.
Name Type Rqd/Opt Description
name String Optional A regular expression used to limit returned objects to those that have a matching name property. If matches are found, the response will be an array with all objects that match. If no match is found, the response will be an empty array.
additional-properties List of String Enum Optional A list of properties to be included in the response in addition to the default properties (element-uri, name, status). This is a list of comma-separated strings where each string is a property name defined in the IO Element object’s data model, or a single asterisk to indicate all appropriate properties.

Response body contents

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

Field name Type Description
io-elements Array of io-element-info objects Array of nested io-element-info objects (described in the next table).

Each nested io-element-info object contains the following fields:

Field name Type Description
element-uri String / URI The element-uri property of the IO Element object.
name String The name property of the IO Element object.
status String Enum The status property of the IO Element object.

Description

This operation lists the IO Elements associated with a particular CPC.

If the name query parameter is specified, the returned list is limited to those IO Elements that have a name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not done.

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 IO Element 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.

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

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the CPC object designated by {cpc-id}.
  • Action/task permission for the IO Element Management task.

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.

The following HTTP status codes are returned for the indicated errors, and 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.
403 (Forbidden) 1 The API user does not have the action/task permission for the IO Element Management task.
404 (Not Found) 1 The object ID in the URI {cpc-id} does not designate an existing CPC object, or the API user does not have object-access permission to the CPC.
4 The CPC designated by the request URI does not support this operation.
409 (Conflict) 8 The target system is not power-on reset complete
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.
503 (Service Unavailable) 1 The request could not be processed because the HMC is not communicating with the SE needed to perform the requested operation.

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

Example HTTP interaction

Figure 1. List IO Elements: Request
GET /api/cpcs/01111b53-7b7a-30ad-97cc-e22d25b35a65/io-elements HTTP/1.1
x-api-session: 4ofsle7yo21gw3vl00v4czg0gwpzykoix367wzrmltqxls9nfd
Figure 2. List IO Elements: Response
200 OK
Cache-control: no-cache
Content-Length: 350
Content-Type: application/json;charset=UTF-8
Date: Tue, 04 Jun 2024 20:30:38 GMT
Server: Hardware management console API web server / 2.0
{
   "io-elements":[
      {
         "element-uri":"/api/cpcs/01111b53-7b7a-30ad-97cc-e22d25b35a65/io-elements/1",
         "name":"1",
         "status":"operating"
      },
      {
         "element-uri":"/api/cpcs/01111b53-7b7a-30ad-97cc-e22d25b35a65/io-elements/4",
         "name":"4",
         "status":"operating"
      },
      {
         "element-uri":"/api/cpcs/01111b53-7b7a-30ad-97cc-e22d25b35a65/io-elements/6",
         "name":"6",
         "status":"operating"
      }
   ]
}