For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.

Devices (GET)

Retrieves metadata for the list of devices that accessed this project.

Note

Since 7.1, the offset parameter is no longer supported. Use the bookmark parameter instead for paging.

Roles

Users in the following roles are authorized to perform this operation:

• mfpadmin
• mfpdeployer
• mfpmonitor
• mfpoperator

Method

GET

Path

/management-apis/2.0/runtimes/runtime-name/devices

Example

https://www.example.com/mfpadmin/management-apis/2.0/runtimes/myruntime/devices?bookmark=ABC&locale=de_DE&orderBy=uid&pageSize=100&query=Jeremy

Path Parameters

runtime-name

The name of the runtime. This is the context root of the runtime web application, without the leading slash.

Query Parameters

Query parameters are optional.

bookmark

The bookmark for the page if only a part of the list (a page) should be returned.

locale

The locale used for error messages.

orderBy

The sort mode. By default, the elements are sorted in increasing order. If the sort mode starts with - (minus sign), the elements are sorted in decreasing order. Possible sort modes are: uid, friendlyName, deviceModel, deviceEnvironment, status, lastAccessed. The default sort mode is: uid.

pageSize

The number of elements if only a part of the list (a page) should be returned. The default value is 100.

query

A device-friendly name or a user to search for.

Produces

application/json, application/xml, text/xml

Response

The metadata of the devices that accessed this project.

JSON Example

{
  "items" : [
    {
      "applicationDeviceAssociations" : [
        {
          "appId" : "com.ibm.app$ios$1.0.0",
          "appName" : "myapplication",
          "certSerialNumber" : "",
          "deviceId" : "12345-6789",
          "deviceStatus" : "LOST",
          "status" : "ENABLED",
        },
        ...
      ],
      "deviceDisplayName" : "Jeremy's Personal Phone",
      "deviceModel" : "Nexus 7",
      "deviceOs" : "4.4",
      "id" : "12345-6789",
      "lastAccessed" : "2014-05-13T00:18:36.979Z",
      "status" : "LOST",
      "userIds" : [
        {
          "str" : "Jeremy",
        },
        ...
      ],
    },
    ...
  ],
  "nextPageBookmark" : "DEF",
  "pageNumber" : 2,
  "pageSize" : 100,
  "prevPageBookmark" : "ABC",
  "productVersion" : "8.0",
  "startIndex" : 0,
  "totalListSize" : 33,
}

XML Example

<?xml version="1.0" encoding="UTF-8"?>
<devices
  nextPageBookmark="DEF"
  pageNumber="2"
  pageSize="100"
  prevPageBookmark="ABC"
  productVersion="8.0"
  startIndex="0"
  totalListSize="33">
  <items>
    <item
      deviceDisplayName="Jeremy's Personal Phone"
      deviceModel="Nexus 7"
      deviceOs="4.4"
      id="12345-6789"
      lastAccessed="2014-05-13T00:18:36.979Z"
      status="LOST">
      <applicationDeviceAssociations>
        <applicationDeviceAssociation
          appId="com.ibm.app$ios$1.0.0"
          appName="myapplication"
          certSerialNumber=""
          deviceId="12345-6789"
          deviceStatus="LOST"
          status="ENABLED"/>
        ...
      </applicationDeviceAssociations>
      <userIds>
        <userId str="Jeremy"/>
        ...
      </userIds>
    </item>
    ...
  </items>
</devices>

Response Properties

The response has the following properties:

items

The array of device metadata

nextPageBookmark

The bookmark of the next page if only one page of devices is returned.

pageNumber

The page index if only one page of devices is returned.

pageSize

The page size if only one page of devices is returned.

prevPageBookmark

The bookmark of the previous or first page if only one page of devices is returned.

productVersion

The exact product version.

startIndex

The start index in the total list if only one page of devices is returned.

totalListSize

The total number of devices.

The device has the following properties:

applicationDeviceAssociations

The applications on the device.

deviceDisplayName

The friendly name of the device.

deviceModel

The device model.

deviceOs

The device operating system.

id

The device id.

lastAccessed

The date in ISO 8601 format when the device was last accessed.

status

The status of the device: ACTIVE, LOST, STOLEN, EXPIRED, DISABLED.

userIds

The applications on the device.

The device application has the following properties:

appId

The application id.

appName

The name of the application.

certSerialNumber

The serial number of the certificate

deviceId

The device id.

deviceStatus

The status of the device:ACTIVE, LOST, STOLEN, EXPIRED, DISABLED.

status

The status of the application: ENABLED or DISABLED.

The user-ids has the following properties:

str

The name of the user

Errors

403

The user is not authorized to call this service.

404

The corresponding runtime is not found or not running.

500

An internal error occurred.

Parent topic: REST API for the MobileFirst Server administration service