The Nokia Notifications Service API (REST API) allows notifications services to access the Nokia Notification Server, and to send notifications to MIDlets on the device.
Notifications services can use the REST API to:
Send notifications to the MIDlets via the Nokia Notification Server.
Use the REST API, if you want to send notifications to the MIDlets via the Nokia Notification Server.
The REST API supports two methods for specifying the recipient of the notifications:
Using the Notification ID
Using the username and Application ID
Note: Using the Notification ID is supported and recommended for devices on Nokia Asha software platform. Using the username and Application ID is supported for devices on earlier platform versions, and for testing purposes.
API calls
The following table summarizes the two REST API calls used to send notifications:
Authentication |
SSL + HTTP Digest Login: Service ID Password: Service Secret |
URL |
Note: Notification ID must be URL encoded.
|
Method |
POST |
API parameters
The following table summarizes the REST API parameters used to send notifications:
Parameter |
Description |
payload |
Notification content. Payload can be max 1536 bytes long. System never touches this part (except for doing compression on the server side and decompression on the client side) - it is always provided to the recipient application "as is". |
wakeup |
Specifies whether an application that is not already running on the device should be started when a notification is received. Note that a notification will only be displayed if the wake up parameter is set TRUE both in the Service API and the Client API. Default value is TRUE. |
alert |
Defines if an alert is to be triggered when notification is received. Valid values TRUE or FALSE. Default value is FALSE. |
ctype |
Specifies the content type of payload as a mime-type (for example, application/xml, text/plain). Maximum length is 255 bytes. |
enc |
Defines the message content encoding (for example, Base64). Maximum length is 32 bytes. |
title |
Notification title. Maximum length is 140 bytes. |
subtitle |
Notification subtitle. Maximum length is 140 bytes. |
type |
Notification type. Maximum length is 20 bytes. |
icon |
Notification icon URI. This URI must point to the resource available publicly in web. Only PNG format icons are supported. Maximum length is 256 octets. |
expires-at |
If the recipient is not available, this parameter defines the time in seconds the notification will be stored for the recipient. Maximum value is 1209600. |
toApp |
ID of the target application. |
HTTP request connection
The notifications service should use a persistent TCP/TLS connection between the HTTP requests. This is particularly important in the production (or Chinese production) environment, where the connection must be persistent.
Service Compatibility
The REST API is compatible with notifications services developed using any scripting or programming language, as it is platform and programming-language independent. The notifications service can be developed using the developer's preferred environment and tools. Most platforms are supported, including Windows, Linux, Unix, and Mac OS.
The REST API is only accessible using the HTTPS protocol, therefore the notifications service needs an HTTPS-capable HTTP client.
cURL is a command-line tool for URL transfers available on most platforms, including Linux, Windows, and Mac OS.
Test the REST API with cURLTo test the notifications service, enter the following command:
curl --digest -u "<SERVICE_ID>:<SERVICE_SECRET>" https://alpha.one.ovi.com/nnapi/1.0/ping
where <SERVICE ID> and <SERVICE_SECRET> parameters are the service credentials
received during registration of the notifications service.
Send a notification using cURL
To send notifications, enter the following command:
curl --digest -u "<SERVICE_ID>:<SERVICE_SECRET>" -d "toapp=<APPLICATION_ID>" -d "payload=Test notification via Notifications API" https://alpha.one.ovi.com/nnapi/1.0/jid/<CLIENT_JID>
where <SERVICE ID>, <SERVICE_SECRET> and <APPLICATION_ID> parameters are the service
credentials received during registration of the notifications service.
The <CLIENT_JID> parameter defines the recipient of the notification
and can be a Nokia Account ID.
The objective of the REST API is to provide a communication channel that allows notifications services to communicate with MIDlets. Nokia does not host the notifications services.
Every notifications service has a base amount of notifications that it can send over one hour. The number of notifications scales up according to the registered MIDlet Notification IDs. The notifications service may check the status of the sent notifications quota using the Query limitations request. If the notifications service has reached the hourly quota, the response code for the request will be 503 until a new hourly period begins. Since the hourly limitation grows with the number of users, the notifications service should not face any problems when growing unless the usage pattern changes.
The Nokia Notification Server can store up to 5 notifications for each user's MIDlet. The maximum expiration time for a notification is 1209600 seconds, which is 14 days. If the storage already contains 5 notifications then all additional notifications to be stored will overwrite the previously stored notifications beginning from the oldest currently stored notification. The notifications are removed from the storage upon the MIDlet coming online or when the notification expires.