16 Device Capabilities

This chapter describes the operations in the Device Capabilities interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.

About the Device Capabilities Interface

Applications use the RESTful Device Capabilities interface to request and receive the a terminal's device ID (such as the IMEI) using getDeviceID or receive the devices device ID type, name of the device/model, and a link to the User Agent Profile XML file using getCapabilities.

REST Service Descriptions Available at Run-time

When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at

http://host:port/rest/device_capabilities/index.html

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Get Capabilities

The Get Capabilities operation retrieves the unique ID for the device type, name of the device/model, and a link to the User Agent Profile XML file.

The request includes the device ID of the device, usually a phone number.

Authorization

Basic

HTTP Method

GET

URI

http://host:port/rest/device_capabilities/device_capabilities?capabilities=${capabilities}

where:

host and port are the host name and port of the machine on which Services Gatekeeper is installed.
${capabilities} is a data object which contains the URI (usually, phone number) as the value of the address attribute.

The following JSON data structure represents this data object in the URI. The value part of each name/value pair indicates its data type:
```
{"address": "URI"}
```

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

There is no request body.

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

The requested device information is returned in a JSON object as the value for the result attribute. It contains the following name-value pairs.

deviceID. String. The device/model number for the URI provided in the request.
name. String. The name of the device.
userAgentProfileReference. String. The link to the User Agent Profile XML file.

The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:

{"result": {
  "deviceId": "String",
  "name": "String",
  "userAgentProfileReference": "URI"
}}

Examples

Example 16-1 Get Capabilities Request

GET rest/device_capabilities/device_capabilities?capabilities=%7B%22address%22%3A%22tel%3A%221234%22%7D HTTP/1.1
X-Session-ID: app:5198750923966743997
Authorization: Basic YXBwX2luc3RhbmNlXzE6d2VibG9naWM=
User-Agent: Jakarta Commons-HttpClient/3.0
Host: 10.182.100.245:9001

Example 16-2 Get Capabilities Response

HTTP/1.1 200 OK
Date: Fri, Nov 05 2010 05:23:27 GMT
Content-Length=124
Content-Type=application/json
X-Powered-By: Servlet/2.5 JSP/2.1
Host: 10.182.100.245:9001

{"result":
      {
        "name":"alice.smith.uiii",
        "deviceId":"0998",
        "userAgentProfileReference":"#1234897897987867gihuyuijlkjlkjllk"
       }
}

Example 16-3 Error Response

HTTP/1.1 500 Internal Server Error
Date: Fri, Nov 05 2010 05:32:27 GMT
Content-Length=131
Content-Type=application/json
X-Powered-By: Servlet/2.5 JSP/2.1

{"error":
      {
        "message":"Invalid input for message part Address",
        "type":"org.csapi.schema.parlayx.common.v3_1.ServiceException",
       }
}

Get Device Id

The Get Device Id operation retrieves the equipment identifier device/name (for example the IMEI number) for a given device. The request includes the device ID, usually a phone number.

The request includes the device ID of the device.