List Adapters of a CPC

The List Adapters of a CPC operation lists the adapters managed by the CPC with the given identifier.

HTTP method and URI

GET /api/cpcs/{cpc-id}/adapters

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

Query parameters:

Name Type Rqd/Opt Description
name String Optional Filter pattern to limit returned objects to those that have a matching name property.
adapter-id String Optional Filter pattern to limit returned objects to those that have a matching adapter-id property.
adapter-family String Enum Optional Filter string to limit returned objects to those that have a matching adapter-family property.

Value must be a valid adapter adapter-family property value.

type String Enum Optional Filter string to limit returned objects to those that have a matching type property.

Value must be a valid adapter type property.

status String Enum Optional Filter string to limit returned objects to those that have a matching status property.

Value must be a valid adapter status 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 (adapter-family, adapter-id, name, object-uri, status, type). This is a list of comma-separated strings where each string is a property name defined in the Adapter 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
adapters Array of adapter-info objects Array of adapter-info objects, described in the next table. Returned array may be empty.

Each nested adapter-info object contains the following fields:

Field name Type Description
object-uri String/ URI Canonical URI path of the Adapter object.
name String The name property of the Adapter object.
adapter-id String The adapter-id property of the Adapter object.
adapter-family String Enum The adapter-family property of the Adapter object.
type String Enum The type property of the Adapter object.
status String Enum The status property of the Adapter object.

Description

This operation lists the adapters that are managed by the identified CPC. The object-uri, name, adapter-id, adapter-family, type, and status are provided for each.

If the object-id {cpc-id} does not identify a CPC object to which the API user has object-access permission, a 404 (Not Found) status code is returned. If the CPC identified by {cpc-id} is not enabled for DPM, an empty list is returned.

If the name or adapter-id query parameters are specified, the returned list is limited to those adapters that have a same-named property matching the specified filter pattern. If the name or adapter-id parameter is omitted, this filtering is not done for the corresponding property.

If the adapter-family, type or status query parameters are specified, the parameter is validated to ensure it is a valid value for the same-named property according to the data model. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid, the returned list is limited to those adapters that have a corresponding property matching the specified value. If the adapter-family, type or status parameter is omitted, this filtering is not done for the corresponding property.

An adapter is included in the list only if the API user has object-access permission for that object. If the specified CPC is a manager of an adapter but the API user does not have permission to it, that object is simply omitted from the list but no error status code results.

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 Adapter 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.

If no adapters are to be included in the results due to filtering or lack of object-access permission, 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 whose object-id is specified in the request URI.
  • Object-access permission to any adapter object to be included in the result.

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. The response body is a standard error response body providing the reason code indicated and associated error message.

Table 1. List Adapters of a CPC: HTTP status and reason codes
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.
14 A query parameter defines an invalid value.
404 (Not Found) 1 A CPC with the object ID {cpc-id} does not exist on the HMC or the API user does not have object-access permission for it.
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 Adapters of a CPC: Request
GET /api/cpcs/87dbe268-0b43-362f-9f80-c79923cc4a29/adapters 
x-api-session:3aonctd6ljeg2k4amfb4sz2rb6yo2esgah7dtlpgofor3rzgk1

<no request body>
Figure 2. List Adapters of a CPC: Response
200 OK
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:30:36 GMT",
"content-type":"application/json;charset=UTF-8",
"content-length":"884",
{
 "adapters":[
  {
   "adapter-family":"osa",
   "adapter-id":"18C",
   "name":"OSD 018C Z15B-04",
   "object-uri":"/api/adapters/e77d39f8-c930-11e5-a978-020000000338",
   "status":"active",
   "type":"osd"
  },
  {
   "adapter-family":"crypto",
   "adapter-id":"1C4",
   "name":"Crypto 01C4 Z15B-21",
   "object-uri":"/api/adapters/f7956dc4-c930-11e5-a978-020000000338",
   "status":"not-active",
   "type":"crypto"
  },
  {
   "adapter-family":"ficon",
   "adapter-id":"141",
   "name":"FCP 0141 Z22B-07",
   "object-uri":"/api/adapters/d71902a4-c930-11e5-a978-020000000338",
   "status":"active",
   "type":"fcp"
  }
 ]
}