Device Capability RESTful API

Device Capability RESTful API

February 21, 2013

The OneAPI Device Capability interface allows a Web application to query the capabilities of a device connected to a network. You can find some examples of why you may want to do this in our use cases.

Resources and URIs

OneAPI Device Capability may be accessed via a RESTful API. A RESTful API utilises HTTP commands POST, GET, PUT, and DELETE in order to perform an operation on a resource at the server. This resource is addressed by a URI; and what is returned by the server is a representation of that resource depending on its current state.

GET is used to retrieve the Device Capability. POST, PUT and DELETE are not used in OneAPI Device Capability. The URIs used are:
http://example.com/{api version}/devicecapabilities/{address}/capabilities HTTP/1.1

  • return a deviceId (IMEI), device name and link to a User Agent profile of the device connected via the {address} in the path.

example.com is replaced by the hostname of the OneAPI server you are accessing. apiVersion optionally indicates the version of OneAPI Device Capability you are accessing – the default is the latest version supported by that server.

Request parameters

Please see the examples below for a description of the request parameters.

Representation formats

The response content type for the Device Capbility API is application/JSON.

Examples and Exceptions

Get the device capability of a mobile account

Request:

GET http://example.com/devicecapabilities/
tel%3A%2B1-555-555-0100/capabilities HTTP/1.1
Accept: application/json
Host: example.com
The resource URL contains:

address The MSISDN or Anonymous Customer Reference of the mobile device. Repeat the address parameter for multiple devices. The protocol and ‘+’ identifier must be used for MSISDN, and must be URL-escaped. %3A represents ‘:’ and %2B represents ‘+’.

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: nnnn
Date: Thu, 04 Jun 2010 02:52:00 GMT

{"deviceCapabilities": {
    "deviceId": "123456789012345",
    "link": {
        "href": "http://example.com/exampleconfigurations/
exampledeviceprofiles/A1234xyz123.xml",
        "rel": "UserAgentProfileReference"
    },
    "name": "MegaPhone 900",
    "resourceURL": "http://example.com/exampleAPI/1/devicecapabilities/tel%3A%2B1-555-555-0100/capabilities"
}}
The JSON response contains a “deviceCapabilities” object.

This contains:

  • deviceId . The IMEI of the device (IMEI is specified by 3GPP TS 23.003).
  • link comprising:
    • a pair for href and a url pointing to a user agent profile for that device type
    • a pair for rel and the type of profile (i.e. User Agent Profile)
  • name of the device

The resourceURL is a self-referring URL to this resource

Response codes and exceptions

HTTP response codes are used to indicate:
200 – Success!
400 – Bad request; check the error message and correct the request syntax.
401 – Authentication failure, check your OneAPI provider’s authentication requirements.
403 – Forbidden; please provide authentication credentials.
404 – Not found: mistake in the host or path of the service URI.
405 – Method not supported: in OneAPI Location v1 only GET is supported.
503 – Server busy and service unavailable. Please retry the request.

More details on these at http://www.ietf.org/rfc/rfc2616.txt

Invalid address error:

HTTP/1.1 400  Bad Request
Content-Type: application/json
Content-Length: 1234
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"requestError": {
    "serviceException": {
        "messageId": "SVC0002",
        "text": " Invalid input value for message part %1",
        "variables": " accessToken abc123"
    }
}}
400 indicates an error

A serviceException describes the reason why the service cannot accept the request; for example if the registrationId was incorrect.

A policyException object means that the request syntax is valid, however an operator policy has been broken: in this example because the operator cannot support the batch size requested.

serviceException and policyException share the same body: an identifier pair for the exception (messageId), a text pair to describe it consistently (text), and a variables pair to indicate any specific cause of the error (variables). The variables relate to the %1 placeholder(s) in the text.

Testing

OneAPI has two Reference Implementations which provide free testing facilities. Please see the OneAPI homepage for details.

Questions and feedback

Please let us know any problems or suggestions for the Data Connection Profile API. Contact details are: OneAPI [at] gsm.org

Reference Material

OneAPI is a profile (subset) of Parlay REST v2.0. The full specifications and guidelines may be found at: http://www.openmobilealliance.org/Technical/current_releases.aspx

Back