Difference between revisions of "Send REST"

Revision as of 18:03, 2 February 2015

Upsidewireless REST API

There are two endpoints of Upsidewireless REST API, [1] and [2]. If you care about more security than performance, you should use the secure endpoint. However, in this case you will need to install certificate for secure, authenticated communication.

In order to use Upsidewireless REST API, you need have an account that has API permissions and get your API credential (token and signature) on your account page. Token is similar to username and signature is similar to password. They are needed in every single call to REST API.

There are two kinds of response of each API call, JSON or XML. You can either use HTTP header ("Accept") or a special HTTP parameter ("responsetype") to specify what kind of response you want. If you want using HTTP header, set either "application/json" or "application/xml" in Accept header. If you want using HTTP parameter, set either "JSON" or "XML" to responsetype parameter. If no response type specified, default response will always be in XML format. Use HTTP header is a highly recommended way to do so.

1. SMS Message API

API URI: /RESTv1/{token}/Message

Support method: HTTP POST

The following parameters are all required in your POST to send the message:

According to different type, a different set of additional parameters is required

'Additional parameters for type: "sms_test'"

'Additional parameter for type: "sms'"

'Additional parameters for type: "mms'"

'Additional parameter for type: "sms_port'"

'Additional parameters for type: "sms_multi'"

'Additional parameters for type: "sms_group'"

'Additional parameters for type: "sms_service_group'"

'Additional parameters for type: "sms_dedicated'"

'Additional parameters for type: "sms_dedicated_port'"

'Additional parameters for type: "sms_defer'"

'Additional parameters for type: "sms_flash'"

'Additional parameters for type: "sms_wappush'"

If no exception in API call, the following response (XML format) will be returned:

<RestResponse>

<HasException>false</HasException>

<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>

< SMSMessage>

<Status>QUEUED or REJECTED</Status>

< Body>sms message</ Body>

< Recipient>16047891236</ Recipient>

<Type>sms</Type>

<TrackingId>MTID256749777469712848</TrackingId>

<RejectReason> </RejectReason>

</ SMSMessage>

</RestResponse>

In SMSMessage, TrackingId and RejectReason are optional. If Status is "QUEUED", for non-multiple recipient type, a unique TrackingId is returned for future query. If Status is "REJECTED", RejectReason includes the reject reason. If type is sms_test, the successful status is "PASSED", not "QUEUED".

Or in JSON format

{

 "HasException": false,
 "Token": "xxxxxxxx-8e4b-405b-998c-a580bf593b76",
 "SMSMessage": {
   "Status": "QUEUED" or "REJECTED",
   "Body": "sms message",
   "Recipient": "16047891236",
   "Type": "sms",
   "TrackingId": "MTID256749777469712848",
   "RejectReason": "Failure message"
 }

}

2. SMS Contact API

API URI: /RESTv1/{token}/Contact

Support method: HTTP POST

The following parameters are required in your POST to add contact:

The following parameters are optional:

If no exception in API call, the following response (XML format) will be returned:

<RestResponse>

<HasException>false</HasException>

<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>

<SMSContact>

<success>true or false</success>

<number>16047891236</number>

<message>Success or failure message</message>

</SMSContact>

</RestResponse>

Or in JSON format {

 "HasException": false,
 "Token": "xxxxxxxx-8e4b-405b-998c-a580bf593b76",
 " SMSContact ": {
   "success": true or false,
   "number": "16047891236",
   "message": "Success or failure message."
 }

}

3. Number Validation API

API URI: /RESTv1/{token}/ NumberValidation

Support method: HTTP POST

The following parameters are required in your POST to do number validation:

If no exception in API call, the following response (XML format) will be returned:

<RestResponse>

<HasException>false</HasException>

<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>

<NumberValidation>

<success>true or false</success>

<number>16047891236</number>

<message>Success or failure message</message>

<country>Canada</country>

<network>British Columbia</network>

<HLRLookupResultObject>

<status>OK</status>

<number>16047891236</number>

<MCC>302</MCC>

<MNC>370</MNC>

<operatorName>Microcell</operatorName>

<operatorCountry>Canada</operatorCountry>

<message></message>

</HLRLookupResultObject>

</NumberValidation>

</RestResponse>

In NumberValidation, country, network and HLRLookupResultObject are optional, depends on the query type. If type is "quick", only country returned; if type is "route", country and network returned; if type is "hlr", only HLRLookupResultObject returned.

Or in JSON format

{

 "HasException": false,
 "Token": "xxxxxxxx-8e4b-405b-998c-a580bf593b76",
 "NumberValidation": {
   "success": true or false,
   "number": "16047891236",
   "message": "Success or failure message.",
   "country": "Canada",
   "network": "British Columbia"
   "HLRLookupResultObject": {
     "status": "OK",
     "number": "16047891236",
     "MCC": "302",
     "MNC": "370",
     "operatorName": "Microcell",
     "operatorCountry": "Canada",
     "message": ""
   }
 }

}

The entire HLRLookupResultObject is as following:

<HLRLookupResultObject>

<status></status>

<number></number>

<MCC></MCC>

<MNC></MNC>

<operatorName></operatorName>

<operatorCountry></operatorCountry>

<IMSI></IMSI>

<MSC></MSC>

<mscOperator></mscOperator>

<mscMCC></mscMCC>

<mscMNC></mscMNC>

<mscCountry></mscCountry>

<mscLocation></mscLocation>

<message></message>

</HLRLookupResultObject>

Only status, number and message are mandatory, others are optional.

  REST API Exception

If there is any exception in REST API call, the HasException flag will be set to true and the following response (XML format) will be returned:

<RestResponse>

<HasException>true</HasException>

<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>

<RestException>

<ErrorCode>101</ErrorCode>

<Message>Unauthorized</Message>

<Status>401</Status>

</RestException>

</RestResponse>

Or in JSON format

{

 "HasException": true,
 "Token": "xxxxxxxx-8e4b-405b-998c-a580bf593b76",
 "RestException": {
   "ErrorCode": "101",
   "Message": "Unauthorized",
   "Status": "401"
 }

}

The Status is HTTP status code and it is optional. ErrorCode and corresponding message:

C# Example

Java Example