Category: Mobile Web Server

This page was last modified 07:31, 1 July 2008.

From Forum Nokia Wiki

Here we describe the Application Programming Interfaces (API) of Mobile Web Server.

REST APIs (since MWS 1.3, Location updated in MWS 1.4)

We have implemented a REST API framework and following APIs. REST APIs follow the mobile site authentication and authorization scheme as such.

NOTES Allowing anonymous access to one of the presence resources causes the authentication for the other two resources to stop working in some configurations. The authentication should still always work when connection filtering is on or if the user first logs in through the MWS web pages.

API XML schemas

http://mymobilesite.net/schema/presence/1.0.0/presence.xsd<br/>
http://mymobilesite.net/schema/presence/1.0.0/availability.xsd<br/>
http://mymobilesite.net/schema/presence/1.0.0/devicestate.xsd<br/>
http://mymobilesite.net/schema/presence/1.1.0/location.xsd<br/>
http://mymobilesite.net/schema/contact_me/1.0.0/sms_message.xsd<br/>

Presence REST API

The Presence web application provides a REST API for accessing terminal presence information in XML format. This REST API provides the following four resources (where domain_name is for example “somedomain.mymobilesite.net”):

http://<domain_name>/rest/presence<br/>
http://<domain_name>/rest/presence/availability<br/>
http://<domain_name>/rest/presence/devicestate<br/>
http://<domain_name>/rest/presence/location<br/>

• Presence resource

The presence resource contains links to the other two resources which contain the actual presence availability and device state information. If user has access to only one of these resources then only that resource is listed in the XML response. Requesting the presence resource will return HTTP_UNAUTHORIZED If user doesn’t have access to either resource. This resource allows only the HTTP GET method. XML schema:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="presence">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" name="availability">
          <xs:complexType>
            <xs:simpleContent>
              <xs:extension base="xs:anyURI">
                <xs:attribute name="xlink" type="xs:anyURI" />
              </xs:extension>
            </xs:simpleContent>
          </xs:complexType>
        </xs:element>
        <xs:element minOccurs="0" name="devicestate">
          <xs:complexType>
            <xs:simpleContent>
              <xs:extension base="xs:anyURI">
                <xs:attribute name="xlink" type="xs:anyURI" />
              </xs:extension>
            </xs:simpleContent>
          </xs:complexType>
        </xs:element>
        <xs:element minOccurs="0" name="location">
          <xs:complexType>
            <xs:simpleContent>
              <xs:extension base="xs:anyURI">
                <xs:attribute name="xlink" type="xs:anyURI" />
              </xs:extension>
            </xs:simpleContent>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

• Availability resource

The availability resource contains the same information that is listed in the main view under the availability information title. Requesting the availability resource will return HTTP_UNAUTHORIZED If user doesn’t have access to availability information. This resource allows only the HTTP GET method. The details of availability information are:

• Profile is a string with a set of possible values defined as an enumeration.
• Calendar_availability and Call state are Boolean values.
• Reserved_for_secs is an integer value. If currently available this value is 0.

XML schema:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="availability">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="profile">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="general" />
              <xs:enumeration value="silent" />
              <xs:enumeration value="meeting" />
              <xs:enumeration value="outdoor" />
              <xs:enumeration value="pager" />
              <xs:enumeration value="offline" />
              <xs:enumeration value="drive" />
              <xs:enumeration value="custom" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="calendar_availability" type="xs:boolean" />
        <xs:element name="reserved_for_secs">
          <xs:simpleType>
            <xs:restriction base="xs:integer">
              <xs:minInclusive value="0" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="call_state" type="xs:boolean" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

• Device state resource

The Device state resource contains the same information that is listed in the main view under the device state title. Requesting the device state resource will return HTTP_UNAUTHORIZED If user doesn’t have access to device state information. This resource allows only the HTTP GET method. The details of device state information are:

• Battery level is an integer value between 0 and 100.
• Localtime is presented as XML dateTime field.
• Connection_type is a string with a set of possible values defined as an enumeration.

XML schema:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="devicestate">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="battery_level">
          <xs:simpleType>
            <xs:restriction base="xs:integer">
              <xs:minInclusive value="0" />
              <xs:maxInclusive value="100" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="localtime" type="xs:dateTime" />
        <xs:element name="connection_type">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="Not connected" />
              <xs:enumeration value="Unknown" />
              <xs:enumeration value="CSD" />
              <xs:enumeration value="3G" />
              <xs:enumeration value="LAN" />
              <xs:enumeration value="CDMA2000" />
              <xs:enumeration value="GPRS" />
              <xs:enumeration value="HSCSD" />
              <xs:enumeration value="EGPRS" />
              <xs:enumeration value="WLAN" />
              <xs:enumeration value="Bluetooth" />
              <xs:enumeration value="Virtual" />
              <xs:enumeration value="Virtual VPN" />
              <xs:enumeration value="CSD (WCDMA)" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

• Location resource

The Location resource contains the same coordinate information that is listed in the Presence main view under the location title. In case of unauthorized access to location information, HTTP_UNAUTHORIZED HTTP status code is returned to the request origin. HTTP GET is the only allowed method to access the device state information via REST API. The details of device state information are:

• Latitude is a decimal value between -90 and 90.
• Longitude is a decimal value between -180 and 180.
• Accuracy is a positive integer value.
• Method is a string with a set of possible values defined as an enumeration.

XML schema:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="location">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="latitude">
          <xs:simpleType>
            <xs:restriction base="xs:decimal">
              <xs:minInclusive value="-90" />
              <xs:maxInclusive value="90" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="longitude">
          <xs:simpleType>
            <xs:restriction base="xs:decimal">
              <xs:minInclusive value="-180" />
              <xs:maxInclusive value="180" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="accuracy">
          <xs:simpleType>
            <xs:restriction base="xs:integer">
              <xs:minInclusive value="0" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="method">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="Bluetooth GPS" />
              <xs:enumeration value="Assisted GPS" />
              <xs:enumeration value="Integrated GPS" />
              <xs:enumeration value="Network-based" />
              <xs:enumeration value="None" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Messaging REST API

This application provides a REST API for 3rd party applications to send messages to the MWS admin’s mobile terminal inbox using a HTTP POST message.

Requesting this REST resource will return HTTP_UNAUTHORIZED If user doesn’t have access to send SMS messages. This resource allows only the POST method.

“http://<domain_name>/rest/inbox/message”

The body of the HTTP POST should contain an XML representation of the sms message to be sent. If the XML representation is missing or corrupt HTTP_NOT_FOUND (404) is returned.

XML Schema for the message:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="message">
    <xs:simpleType>
      <xs:restriction base="xs:string">
        <xs:minLength value="0" />
        <xs:maxLength value="500" />
      </xs:restriction>
    </xs:simpleType>
  </xs:element>
</xs:schema>

RSS feeds (since MWS 1.2)

Mobile domain statuses can be followed via RSS from our gateway (like this [1] where id is the domain name). This is how our widgets work.

Blog entries and gallery files can be accessed via RSS as from the device (like this: [2])

Other RSS feeds might be added in the future, based on feedback.

Badge

The mobile site badge can be fetched from the gateway with a code like this: <a target="_blank" href="http://demo.mymobilesite.net"><img border="0" name="thumbimgs" id="thumbimg0" src="http://mymobilesite.net/services/badges/demo/0/0/"/></a>

Where demo is the actual domain name.

DIY

If there is no suitable API available, one can just implement the needed functionality (in Python). That is how the desktop widgets were developed, and there is an article available about the experience in Desktop widgets.

Comments

Please describe here your ideas for new APIs or changes/fixes to existing.