Device List REST Service
Use Device List REST Service to list information about all devices of a specific device group, or a device in the IBM Security Guardium Key Lifecycle Manager database.
Device List REST Service supports pagination. The following parameters are used for pagination:
offset
and
count
. The offset
value specifies the page number from which the
records are displayed. The count
value specifies the number of records to display
on a page, which you specify in the offset
value. For example, to retrieve the
first 10 records for the list, set offset = 1 and count =
10. To retrieve the next 10 records, set offset = 2 and
count = 10. If you do not specify values for pagination parameters, the first
2000 records are returned.- Operation
GET
- URL
-
- To retrieve all devices:
- https://<host>:<port>/SKLM/rest/v1/devicesNote: Returns the first 2000 records.
- To retrieve a specific list:
- https://<host>:<port>/SKLM/rest/v1/devices?type=<type>&uuid=<uuid>Note: Returns the first 2000 records.
- To retrieve a specific list with pagination:
- https://<host>:<port>/SKLM/rest/v1/devices?type=<type>&uuid=<uuid>&offset=<offset>&count=<count>
By default, Guardium Key Lifecycle Manager server listens to the secure port 9443 (HTTPS) for communication. During IBM Security Guardium Key Lifecycle Manager installation, you can modify this default port.
Request
Request parameters
Parameter | Description |
---|---|
host | Specify the IP address or host name of the IBM Security Guardium Key Lifecycle Manager server. |
port | Specify the port number on which the IBM Security Guardium Key Lifecycle Manager server listens for requests. |
Type | Specify the device group type. The default is
all device groups.
|
uuid | Specify the unique ID of the device. For example: DEVICE-74386920-148c-47b2-a1e2-d19194b315cf |
offset | Specify the page number from which the records are displayed based on the value that you specify for count. |
count | Specify the number of records to display on the specified page (offset). The first 2000 records are returned if you do not specify the value for offset and count. |
Request Headers
Header name | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Authorization | SKLMAuth userAuthId=<authIdValue> |
Accept-Language | Any valid locale that is supported by IBM Security Guardium Key Lifecycle Manager. For example, en or de. |
Response
Response Headers
Header name | Value and description |
---|---|
Status Code |
|
Content-Type | application/json |
Content-Language | Locale for the response message. |
Success response body
JSON object with the following specification:
JSON property name | Description |
---|---|
Description | Describes the type of device or its purpose. |
Serial Number | Returns the serial number as an ASCII string. |
Device uuid | Returns the unique ID of the device. |
Device group | Returns the device group type. This property
can contain the following device groups:
|
World wide name | Returns the device name, which is a nonsecure address, which is used in combination with other device information, such as a serial number. You can use this name to define devices and device paths. |
Sym alias | Returns an alias to identify an existing key
group for an LTO tape drive. The attribute is also
used for the DS5000 storage server to change or associate a new device
key container. |
Host address | Returns the host address for the device. |
Key alias 1 | Returns the default key alias for a certificate
that is used by a 3592 tape drive or a DS8000 Turbo
drive. This alias is not used for an LTO tape drive
or DS5000 storage server. |
Key alias 2 | Returns a key alias for a 3592 tape
drive or a DS8000 Turbo drive. This alias is not
used for an LTO tape drive or DS5000 storage
server. |
Certificate length | Returns the length of the actual certificate that identifies the device. |
Device Text | Returns a unique text that describes a DS5000 storage server. The text ranges is up to 96 bytes, but it must be greater than 0. |
Current Key | Returns the current key for the device. |
Error Response Body
JSON object with the following specification.
JSON property name | Description |
---|---|
code | Returns the application error code. |
message | Returns a message that describes the error. |
Examples
- Service request to list device information
GET https://<host>:<port>/SKLM/rest/v1/devices Content-Type: application/json Accept : application/json Authorization : SKLMAuth userAuthId=37ea1939-1374-4db7-84cd-14e399be2d20 Accept-Language : en
- Success response
Status Code : 200 OK Content-Language: en [ { "Description": "salesDivisionDrive", "Serial Number": "FAA49403AQJF", "Device uuid": "DEVICE-641b963e-aa61-46f8-a036-12023768427a", "Device group": "LTO", "World wide name": "ABCDEF1234567890", "Sym alias": "satGroup" }, { "Description": "salesDivisionDrive", "Serial Number": "FAA49403AQJ1", "Device uuid": "DEVICE-4c3d0117-79a7-411e-a568-83481adc8332", "Device group": "LTO", "World wide name": "ABCDEF1234567891", "Sym alias": "satGroup" }, { "Description": "salesDivisionDrive", "Serial Number": "FAA49403AQJ2", "Device uuid": "DEVICE-1fe2e310-6c2e-471f-96fd-838f03ac0d5d", "Device group": "LTO", "World wide name": "ABCDEF1234567892", "Sym alias": "satGroup" }, { "Description": "salesDivisionDrive", "Serial Number": "FAA49403AQJ3", "Device uuid": "DEVICE-7890b61a-398c-4e61-afc0-8007a7274bc9", "Device group": "LTO", "World wide name": "ABCDEF1234567893", "Sym alias": "satGroup" }, ]
- Error response
Status Code : 400 Bad Request Content-Language: en {"code" "CTGKM6002E" , "message": "CTGKM6002E Bad Request: Invalid user authentication ID or invalid request format." }