MUSE 3 REST-W | RESTful Wrapper Help

Mobile MUSE 3 RESTful Wrapper Help

Preamble

Welcome the the RESTful Wrapper (REST-W). The REST-W encapsulates the SOAP API. This allows JavaScript and Flash developers a easy, more friendly access to the SAOP API. This help page has 2 main sections; a REST-W to SOAP mapping table and details, with examples, about all REST-W URLs.

REST-W to SOAP Mapping

REST-W URLSOAP Function
GET/components GetSubscriptions()
GET/components/[Component Name] GetComponentInfo() + IsSubscribed()
POST/components/[Component Name]/auth componentAuthenticate()
POST/components/[Component Name]/connect componentConnect()
GET/services ListServicePoints()
GET/services/account GetUserInfo() + GetCreditBalance()
POST/services/auth userAuthenticate()
GET/services/[Service Name] GetAttributes() + GetThruput() + getCallBackURL()
POST/services/[Service Name] ControlServiceInterface()
POST/services/[Service Name]/callback setCallBackURL()
GET/services/[Service Name]/location
/services/[Service Name]/location/[Phone#(,...)]		 QueryLocation()
POST/services/[Service Name]/location Set location via ControlServiceInterface()
POST/services/[Service Name]/mms sendMMSURL()
POST/services/[Service Name]/sms
/services/[Service Name]/sms/[Phone#(,...)]
/services/[Service Name]/sms/[Phone#(,...)]/[Message]		 sendSMS()
POST/services/[Service Name]/wappush sendWAPPush()
POST/services/[Service Name]/transcode transcodeSubmitURL()
Unsupported SOAP functions:  sendMMSFile(), transcodeSubmitFile(), transcodeSubmitFileOrURL()
*** NOTE: URL parts enclosed in [] indicate the part is dynamic text based on user access, choice, availability, etc. ***

REST-W HTTP Requests

Data must be sent via POSTs and must be formated as a POST string (unless otherwise noted), for example:

user_name=jerry&password=chee$y!pizza

REST-W HTTP Responses

Authenticate

You can authenticate 2 ways: programatically or manually. To program in authentication into your application/webpage POST to the /components/[Component Name]/auth or the /services/auth URL. Alternately you can navigate, with your browser, to any URL and you will be prompted for a User Name and Password/Auth String.

When authenticating programatically you need not login for each request. You can use sessioning to get more timely responses. To do this you must retain the Auth Tokens returned by the Auth URLS and inclued the following HTTP header when requesting for REST-W:

Authorization: AuthSub appname="YOUR_APPLICATION_NAME" token="AUTH_TOKEN"


All URLs require an Auth Token under the REST-W realm.

Success

All successful POSTs and GETs will return the HTTP status code of 200 followed by the requested data if any. Check the REST-W URL Details section for more information.

Errors

Two types of errors can occur when POSTing or GETing URLs: URL errors and processing errors. URL error return and HTTP status code of 404 and are returned when a requested URL does not exist. Processing errors return a HTTP status of 400 and are cause either by the user or server. Details about the error are returned in XML with the root element . Errors contain details of what when wrong. These details can either be text or additional XML elements (which would be return from the SOAP function call), for example:

<error id="RW101">Malformed HTTP header</error>


Error IDs that begin with RW are error that original within REST-W. Error IDs that do not that the RW prefix are errors returned by the wrapped SOAP function.

REST-W JavaScript Example

A working example of sending an SMS message can be found at the following URL: /example. Do a "View Page Source" to see the code.

REST-W URL Details

/components

HTTP GET

Description:  Returns a list of components the User Name is subscribed to.

Request Data to Send:  user_name

Successful Response:  
     <pre>
          <a id="Mobile Engage" href="/components/Mobile_Engage">/components/Mobile_Engage</a>
          <a id="Mobile Dialog" href="/components/Mobile_Dialog">/components/Mobile_Dialog</a>
            .
            .
            .
     </pre>

/components/[Component Name]

HTTP GET

Description:  Returns information/attributes about the component.

Request Data to Send:  user_name

Successful Response:  
     <component>
          <is_subscribed>1</is_subscribed>
            .
            .
            .
     </component>

/components/[Component Name]/auth

HTTP POST

Description:  Authorize a username/auth string pair for that comonent and create a session.

Request Data to Send:  user_name, auth_string

Successful Response:  
     <auth_token>890sgf70sdgu04958KJHk</auth_token>

/components/[Component Name]/connect

HTTP POST

Description:  Get REST direct access to use a component.

Request Data to Send:  developer_id, auth_string, user_name

Successful Response:   (return a SOAP QMResult)
     <result>
          <token>...</token>
          <url>...</url>
          <status>...</status>
     </result>

/services

HTTP GET

Description:  Returns a list of services the authenticated user is subscribed to.

Request Data to Send:  n/a

Successful Response:  
     <pre>
          <a id="SMS OR MMS" href="/services/SMS_OR_MMS">/services/SMS_OR_MMS</a>
          <a id="Location Query" href="/services/Location_Query">/services/Location_Query</a>
            .
            .
            .
     </pre>

/services/account

HTTP GET

Description:  Returns a information/attributes about the authenticated user.

Request Data to Send:  n/a

Successful Response:  
     <account>
            .
            .
            .
     </account>

/services/auth

HTTP POST

Description:  Authorize a username/password pair for all services and create a session.

Request Data to Send:  user_name, password

Successful Response:  
     <auth_token>890sgf70sdgu04958KJHk</auth_token>

/services/[Service Name]

HTTP GET

Description:  Returns information/attributes about the service.

Request Data to Send:  n/a

Successful Response:  
     <service>
          <callback_url>1</callback_url>
          <thruput>1</thruput>
            .
            .
            .
     </service>

HTTP POST

Description:  Used to control the service interface.

Request Data to Send:  xml data (no POST string needed)

Successful Response:  (return a SOAP QMResult)
     <result>
          <token>...</token>
          <url>...</url>
          <status>...</status>
     </result>

/services/[Service Name]/callback

HTTP POST

Description:  Set the callback URl for the service.

Request Data to Send:  callback_url

Successful Response:  (return a SOAP QMResult)
     <result>
          <token>...</token>
          <url>...</url>
          <status>...</status>
     </result>

/services/[Service Name]/location

/services/[Service Name]/location/[Phone#(,...)]

HTTP GET

Description:  Return loation information for supplied mobiles.

Request Data to Send:  force (0 or 1, optional), phone_list (comma seporated) *** Only supply if NOT part of the URL ***

Successful Response:  
     <locations>
            <location>...</location>
            .
            .
            .
     </locations>

HTTP POST

Description:  Sets the loation information for a mobile through an LBS Service Point.

Request Data to Send:  phone_number, x, y, z, radius

Successful Response:   (return a SOAP QMResult)
     <result>
          <token>...</token>
          <url>...</url>
          <status>...</status>
     </result>

/services/[Service Name]/mms

HTTP POST

Description:  Send a MMS message.

Request Data to Send:  phone_list (comma seporated), url, message

Successful Response:   (return a SOAP QMResult)
     <result>
          <token>...</token>
          <url>...</url>
          <status>...</status>
     </result>

/services/[Service Name]/sms

/services/[Service Name]/sms/[Phone#(,...)]

/services/[Service Name]/sms/[Phone#(,...)]/[Message]

HTTP POST

Description:  Send a SMS message.

Request Data to Send:  phone_list (comma seporated), message *** Only supply if NOT part of the URL ***

Successful Response:   (return a SOAP QMResult)
     <result>
          <token>...</token>
          <url>...</url>
          <status>...</status>
     </result>

/services/[Service Name]/wappush

HTTP POST

Description:  WAP Push a message.

Request Data to Send:  phone_list (comma seporated), url, message

Successful Response:   (return a SOAP QMResult)
     <result>
          <token>...</token>
          <url>...</url>
          <status>...</status>
     </result>

/services/[Service Name]/transcode

HTTP POST

Description:  Send a Transcode message.

Request Data to Send:  name_on_device, sms_service_name, use_push, phone_list (comma seporated), url, message

Successful Response:   (return a SOAP QMResult)
     <result>
          <token>...</token>
          <url>...</url>
          <status>...</status>
     </result>

<EOF />