Data Connection Profile

Data Connection Profile

February 21, 2013

The OneAPI Data Connection Profile interface allows a Web application to query the connection type (e.g. 3G, GPRS etc.) and roaming status of one or more devices connected to a mobile network. You can find some examples of why you may want to do this in our use cases.

Resources and URIs

OneAPI Data Connection Profile 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 Terminal Status. POST, PUT and DELETE are not used in OneAPI Data Connection Profile. The URIs used are:

http://example.com/{api version}/terminalstatus/queries/connectionType?address={terminalId}

  • Request the connection type (3G, GPRS etc.) of the terminal identified by {address}. The value of {address} will usually be an MSISDN or Anonymous Customer Reference which identifies a specific mobile account (e.g. a mobile phone or laptop dongle).

http://example.com/{api version}/terminalstatus/queries/roamingStatus?address={terminalId}

  • Request the connection type of the terminal identified by {address}. The value of {address} will usually be an MSISDN or Anonymous Customer Reference which identifies a specific mobile account (e.g. a mobile phone or laptop dongle).

example.com is replaced by the hostname of the OneAPI server you are accessing. apiVersion optionally indicates the version of OneAPI Data Connection Profile 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 Data Connection Profile API is application/JSON.

Examples and Exceptions

Get the connection type of a network-connected device

Request:

GET http://example.com/terminalstatus/queries/connectionType?
address=tel%3A%2B1-555-555-0100
HTTP/1.1
Accept: application/json
Host: example.com
Mandatory parameters

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 2009 02:51:59 GMT

{"terminalConnectionTypeList": {
    "connectionType": {
        "address": "tel:+1-555-555-0100",
        "currentConnectionType": "GPRS",
        "retrievalStatus": "Retrieved"
    },
    "resourceURL": 
"http://example.com/exampleAPI/1/terminalstatus/
queries/connectionType"
}}
The JSON response contains a “terminalConnectionTypeList” object. This contains one “connectionType” array – this contains one or more array member objects, of the following structure (there will be multiple array members if multiple addresses have been queried).

  • address
  • currentConnectionType. Value is one of:
    • EDGE
    • GPRS
    • UMTS
    • HSDPA
    • HSUPA
    • HSPA+
    • LTE
    • WLAN
    • PACKET
    • WCDMA
    • CDMA
    • TD-SCDMA
    • WiMAX
  • retrievalStatus. Value is one of “Retrieved”or “Error”

The resourceURL is a self-referring URL to this resource

Retrieve the customer’s roaming status

Request:

GET http://example.com/terminalstatus 
/queries/roamingStatus?address=tel%3A%2B1-555-555-0100 HTTP/1.1
Accept: application/json
Host: example.com 
Mandatory Parameters

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 2009 02:51:59 GMT

{"terminalRoamingStatusList": {
    "roaming": {
        "address": "tel:+1-555-555-0100",
        "currentRoaming": "InternationalRoaming",
        "retrievalStatus": "Retrieved",
        "servingMccMnc": {
            "mcc": "310",
            "mnc": "010"
        },
    }   
    "resourceURL": 
    "http://example.com/exampleAPI/1/terminalstatus/
queries/roamingStatus"
}}
The JSON response contains a “terminalRoamingStatusList” object. This contains one “roaming” array listing one or more array member objects, of the following structure (there will be multiple array members if multiple addresses have been queried).

  • address
  • currentRoaming. Value is one of:
    • InternationalRoaming ; terminal is in a different country from that in which it is registered with a home operator
    • DomesticRoaming ; terminal is connected to another operator in the terminal’s registered home country
    • NotRoaming ; terminal is connected to its home operator
  • servingMccMnc. Contains the serving network country code/ network code
    • mcc the mobile country code of the serving operator according to ITU-T recommendation E.212
    • mnc the mobile network code of the serving operator according to ITU-T recommendation E.212
  • retrievalStatus . Value is one of “Retrieved” or “Error”
  • errorInformation (optional)

The resourceURL is a self-referring URL

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": "SVC0004",
        "text": "No valid addresses provided in message part %1",
        "variables": "%1 - request URI"
    }
}}
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
Contact GSMA Legal Email Preference Centre Copyright © 2014 GSMA. GSM and the GSM Logo are registered and owned by the GSMA.