Welcome to Moxie Notifications’s documentation!¶
HTTP API¶
Endpoint¶
Format¶
Dates are expressed as YYYY-mm-DDTHH:mm:ss (e.g. 2013-11-08T16:00:00)
Methods¶
Endpoint to create and retrieve notifications
Warning
All the routes below refer to the root of the module. The identifier of the module should be concatenated (e.g. route / should be concatenated with the name of the module, /notifications).
- POST /¶
Create a new notification
Requires authentication
Example request:
POST /notifications HTTP/1.1 Host: api.m.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f Content-Type: application/json { "message": "Bomb threat at X", }
Example response:
HTTP/1.1 201 Created Location: /notifications/774aaaa5-d45b-4687-b7fb-d59aae606eb9 { "ident": "774aaaa5-d45b-4687-b7fb-d59aae606eb9", "status": "created" }
Json Parameters: - message (string) – the message of the notification
- timestamp (date) – (optional) start date of the notification (defaults to current time)
- expires (date) – (optional) end date of the notification (defaults to one hour after current time)
- url (string) – (optional) url describing the notification
- label (string) – (optional) label describing the notification
Status Codes: - 201 – 201 Created: notification created
- 400 – 400 Bad Request
- 401 – 401 Unauthorized
- POST /push¶
Request a notification to be pushed to registered devices
Requires authentication
Example request:
POST /push HTTP/1.1 Host: api.m.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f Content-Type: application/json { "notification": "{uuid}", "message": "Bomb threat at X, avoid the area" }
Example response:
HTTP/1.1 202 Accepted
Json Parameters: - notification (string) – unique identifier of the notification
- message (string) – message of the push notification
Status Codes: - 202 – 202 Accepted: push request queued
- 400 – 400 Bad Request
- 401 – 401 Unauthorized
- POST /(string: uuid)¶
Update a notification
Requires authentication
Example request:
POST /notifications/X HTTP/1.1 Host: api.m.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f Content-Type: application/json { "message": "Bomb threat at X, avoid the area!", }
Example response:
HTTP/1.1 200 OK Location: /notifications/{uuid}
Parameters: - uuid (string) – unique identifier of the notification
Json Parameters: - message (string) – the message of the notification
- timestamp (date) – (optional) start date of the notification
- expires (date) – (optional) end date of the notification
- url (string) – (optional) url describing the notification
- label (string) – (optional) label describing the notification
Status Codes: - 200 – 200 OK: update applied correctly
- 400 – 400 Bad Request
- 401 – 401 Unauthorized
- 404 – 404 Not Found: notification not found
- POST /(string: uuid)/followup¶
Add a follow up to an existing notification
Requires authentication
Example request:
POST /notifications/X/followup HTTP/1.1 Host: api.m.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f Content-Type: application/json { "message": "security services have arrived on scene", }
Example response:
HTTP/1.1 201 Created Location: /notifications/X/followup/1
Parameters: - uuid (string) – unique identifier of the notification
Json Parameters: - message (string) – the message of the follow up
- timestamp (date) – (optional) date of the follow up
Status Codes: - 201 – 201 Created: followup created
- 400 – 400 Bad Request
- 401 – 401 Unauthorized
- 404 – 404 Not Found: notification not found
- POST /(string: uuid)/followup/(string: id)¶
Update a follow up
Requires authentication
Example request:
POST /notifications/X/followup/1 HTTP/1.1 Host: api.m.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f Content-Type: application/json { "message": "Fire department working", }
Example response:
HTTP/1.1 200 OK Location: /notifications/{uuid}/followup/1
Parameters: - uuid (string) – unique identifier of the notification
- id (string) – identifier of the followup
Json Parameters: - message (string) – the message of the follow up
- timestamp (date) – (optional) date of the follow up
Status Codes: - 200 – 200 OK: update applied correctly
- 400 – 400 Bad Request
- 401 – 401 Unauthorized
- 404 – 404 Not Found: notification not found or followup not found
- DELETE /(string: uuid)¶
Delete a notification
Requires authentication
Example request:
DELETE /notifications/X HTTP/1.1 Host: api.m.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f
Example response:
HTTP/1.1 200 OK
Parameters: - uuid (string) – unique identifier of the notification
Status Codes: - 200 – 200 OK: notification deleted
- 401 – 401 Unauthorized
- 404 – 404 Not Found: notification not found
- DELETE /(string: uuid)/followup/(string: id)¶
Delete a follow up
Requires authentication
Example request:
DELETE /notifications/X/followup/1 HTTP/1.1 Host: api.m.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f
Example response:
HTTP/1.1 200 OK
Parameters: - uuid (string) – unique identifier of the notification
- id (string) – identifier of the follow up
Status Codes: - 200 – 200 OK: follow up deleted
- 401 – 401 Unauthorized
- 404 – 404 Not Found: notification not found or follow up not found
- GET /¶
Get ongoing notifications
Example request:
GET /notifications HTTP/1.1 Host: api.m.ox.ac.uk Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "notifications": [ { "uuid": "X", "timestamp": "2013-02-08T12:30", "message": "Bomb threat at X", "expires": "2013-02-08:16:00", "followups": [ { "timestamp": "2013-02-08T13:30", "id": 1, "message": "bla bla" }, ... ] } ] }Query Parameters: - history – boolean value (“true”, “True”, “1”, “t”) to display all notifications (defaults to false)
Status Codes: - 200 – 200 OK
- GET /(string: uuid)¶
Get a notification
Example request:
GET /notifications/X HTTP/1.1 Host: api.m.ox.ac.uk Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "uuid": "X", "timestamp": "2013-02-08T12:30", "message": "Bomb threat at X, "expires": "2013-02-08:16:00", "followups": [ { "timestamp": "2013-02-08T13:30", "id": 1, "message": "bla bla" }, ... ] }Status Codes: - 200 – 200 OK
- 404 – 404 Not Found: notification not found
Typical scenario when using the API to create a notification¶
Create a new notification¶
- POST /notifications¶
Request:
POST /notifications HTTP/1.1 Host: api.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f Content-Type: application/json { "message": "Bomb threat at X", "expires": "2013-11-08T16:00:00", }
Response:
HTTP/1.1 201 Created Location: /notifications/16d4a94fc58111a323437ec363d71f5a
(Optionally) push the notification to registered devices¶
- POST /push¶
Request:
POST /push HTTP/1.1 Host: api.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f Content-Type: application/json { "notification": "16d4a94fc58111a323437ec363d71f5a", "message": "Bomb threat at X, avoid the area" }
Response:
HTTP/1.1 202 Accepted
Add a follow up¶
- POST /notifications/16d4a94fc58111a323437ec363d71f5a/followup¶
Request:
POST /notifications/16d4a94fc58111a323437ec363d71f5a/followup HTTP/1.1 Host: api.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f Content-Type: application/json { "message": "security services have arrived on scene", }
Example response:
HTTP/1.1 201 Created Location: /notifications/16d4a94fc58111a323437ec363d71f5a/followup/1
Update the notification to be displayed until the end of the day¶
- POST /notifications/16d4a94fc58111a323437ec363d71f5a¶
Request:
POST /notifications/16d4a94fc58111a323437ec363d71f5a HTTP/1.1 Host: api.ox.ac.uk X-Moxie-Key: d51459b5-d634-48f7-a77c-d87c77af37f1 X-HMAC-Nonce: 12642 Date: Fri, 10 Jan 2014 11:49:55 GMT Authorization: ccd61eddf0c6be849b13e524c171e4c14a0d571f Content-Type: application/json { "expires": "2013-02-08T18:00:00" }
Response:
HTTP/1.1 200 OK Location: /notifications/16d4a94fc58111a323437ec363d71f5a
Developer¶
Configuration¶
Database¶
You do need to have a database configured, the key SQLALCHEMY_DATABASE_URI in the flask section should be documented.
See SQLAlchemy documentation for more information on engines.
flask:
SQLALCHEMY_DATABASE_URI: 'sqlite:////tmp/test.db'
NotificationsService¶
NotificationsService is configured with the API key’s and shared secrets of users configured to use the notifications.
- users
- Mapping of API keys (chosen however you want) to shared secrets (used by the client to create HMAC requests).
moxie_notifications.providers.gcm.GCMProvider:¶
- api_key
- API Key obtained from Google.
- url
- (optional) URL to GCM Server.
moxie_notifications.providers.apns.APNSProvider:¶
- address
- Address to APNS server.
- cert_file
- Path to the certificate file (PEM format) registered with APNS.
- key_file
- (optional) Path to key in PEM format from file.
- passphrase
- (optional) Passphrase for private key file.
moxie_notifications.providers.mail.EmailNotificationsProvider¶
This is mainly used for development purpose.
- smtp_server
- Address of the SMTP server
- sender_email
- Email address of the sender
- send_to
- List of email addresses where notifications should be send to
Example Configuration¶
notifications:
NotificationsService:
users:
myuserapikey: 'usersharedsecret'
anotheruserapikey: 'secondsharedsecret'
providers:
moxie_notifications.providers.gcm.GCMProvider:
api_key: 'APIKEY'
moxie_notifications.providers.apns.APNSProvider:
address: 'push_sandbox'
cert_file: '/srv/moxie/foo.pem'
moxie_notifications.providers.mail.EmailNotificationsProvider:
smtp_server: 'smtp.com'
sender_email: 'noreply@msmsms.com'
send_to: ['user@msmsmsms.com']
KVService:
backend_uri: 'redis://localhost:6379/4'
Models¶
A notification is the top-level object which MAY contain a number of followup.
Notification¶
Properties:
- message: main content of the notification
- timestamp: date when the notification has been created
- expires: notification valid until given date
- url: (optional) url to attach to the notification
- label: qualifier of the notification (e.g. “flood”, “security”)
Relations:
- list of followup
Follow up¶
Properties:
- message: message of the follow up
- timestamp: date of the follow up
Relations:
- notification: parent notification of the follow up
Push notification¶
Properties:
- message: message of the push notification (restricted to X characters)
Relations:
- notification: related notification for this push notification