22 Adding RESTful WAP Push Support

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/push_message/messages

where host and port are the host name and port of the system on which Services Gatekeeper is installed.

Request Header

The request headers depend on the type of message:

• If the message content is in the form of an attachment, the request will be multipart and the request header must contain the header fields that describe the parts of the message.

• If the message does not contain an attachment, the special headers associated with the multipart messaged are not used.

Message Part Content

The message part content for this operation accepts the following parameters:

• destinationAddresses: String. Required. An array of terminal addresses.

  Each of the addresses in this array should be formatted according to the Push Proxy Gateway Service Specification (WAP-249-PPGService-20010713-a).

• pushId: String. Required. A unique identifier provided by the application. Supported types are PLMN and USER.

• replaceMethod: String. Required. Valid entries are:

  • all

  • pendingOnly

  replaceMethod is used in conjunction with the pushId parameter and defines how to replace a previously sent message. This entry will be ignored if replacePushId is NULL.

• requesterId: String. Required. The application ID as given by the operator.

• serviceCode: String. Required. A code for charging purposes.

• additionalProperties. An array of JSON objects. Optional.

  Each element in the array is a JSON object used to add additional properties with the following parameters:

  • name: String. Required if the additionalProperties object is present. Valid entries include pap.priority, pap.delivery-method, pap.network-required, pap.bearer, and pap.bearer-required.

  • value: String. Required if the additionalProperties object is present. The value associated with the property.

• deliverAfterTimeStamp: String. Optional. The date and time after which the content should be delivered to the wireless device. This entry is in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss.

  If the network does not support this parameter, this entry will be rejected.

• deliverBeforeTimeStamp: String. Optional. The date and time by when the content should be delivered to the wireless device. This entry is in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss.

  If the network does not support this parameter, this entry will be rejected.

• progressNoteRequested. Boolean. Optional. If true, the application wishes to receive progress notes at the address specified by the resultNotificationEndpoint.

• replacePushId: String. Optional. The Push Id of the message that is to be replaced. If it is set to NULL, the message is treated as a new message. If it is set to a valid ID, message replacement will occur for all currently pending messages. Messages that have already been delivered cannot be canceled, and therefore cannot.

  Messages that have already been delivered cannot be canceled, and therefore cannot be replaced

• resultNotificationEndpoint: String. Optional. The URI which represents the endpoint address to which the notification should be delivered. This string should be a Bayeux protocol channel name that begins with /bayeux/appInstanceID where appInstanceID is the client application's application instance account ID.

  If the application does not wish to receive notifications, this value should be NULL.

• sourceReference: String. Optional. The name of the service provider.

The message part content for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:

{
  "destinationAddresses": ["String"],
  "pushId": "String",
  "replaceMethod": "all|pending-only",
  "requesterID": "String",
  "serviceCode": "String",
  "additionalProperties": [{
    "name": "String",
    "value": "String"
  }],
  "deliverAfterTimestamp": "Calendar",
  "deliverBeforeTimestamp": "Calendar",
  "progressNotesRequested": "Boolean",
  "replacePushId": "String",
  "resultNotificationEndpoint": "URI",
  "sourceReference": "String"
}

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".

Response Body

The response body is a nested JSON object. It contains the result attribute with the following attributes and data objects:

• pushId: String. Required. A unique identifier provided by the application. Supported types are PLMN and USER.

• result: JSON object. This object contains the outcome code. It contains the following two entries:

  • code: String. The outcome code generated by the network node. Table 22-1 lists the possible values.

  • description: String. The textual description for the code.

• additionalProperties: An array of JSON objects used to add additional properties.

  Each element in the array is a JSON object with the following parameters:

  • name: String. The name of an additional property. One of: pap.stage, pap.note, pap.time.

  • value: String. The value associated with the property.

• replyTime: String. The date and time for the reply in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss.

• senderAddress: String. Optional. The sender's address.

• senderName: String. Optional. The sender's name.

The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:

{"result": {
  "pushId": "String",
  "result": {
    "code": "String",
    "description": "String"
  },
  "additionalProperties": [{
    "name": "String",
    "value": "String"
  }],
  "replyTime": "Calendar",
  "senderAddress": "String",
  "senderName": "String"
}}

Result Notification Message Object

The resultNotificationMessage object delivered to the resultNotificationEndpoint address is a nested JSON object containing the following entries:

• address: String. The address of the terminal to which this message is sent.

• code: String. The final state of the message, one of the values listed in Table 22-1.

• messageState: String. The state of the message. One of:

  • rejected

  • pending

  • delivered

  • undelivered

  • expired

  • aborted

  • timeout

  • cancelled

  • unknown

• pushId: String. The unique identifier defined in the initial request, used for correlation.

• additionalProperties. An array of JSON objects used to add additional properties.

  Each element in the array is a JSON object with the following parameters:

  • name: String. The name of an additional property, dependent on the network node. One of: pap.priority, pap.delivery-method, pap.network-required, pap.bearer, and pap.bearer-required.

  • value: String. The value associated with the property.

• description: String. A description of the notification provided by the network. (May not be provided).

• eventTime: String. The date and time the message reached the destination in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss.

• receivedTime: String. The date and time the message was received at the network node in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss.

• senderAddress: String. Optional. The sender's address.

• senderName: String. Optional. The sender's name.