-
Notifications
You must be signed in to change notification settings - Fork 0
Push API
In order to get push notifications on iOS devices to notify users about grade changes, the device must communicate with the server to exchange some information. As iOS does not permit processes to run in the background, and background fetch is not suitable for this purpose, the server must do the scraping of the gradebook, and compare this data against a stored dataset, and queuing notifications as needed.
Therefore, the "QuickHAC Push API" was created. This API is a defined way for the device to exchange information about notification state and the accounts associated with it.
Endpoint: https://api.quickhac.com/ios/
All requests must be send to the above URL, over HTTPS. Requests over plain HTTP will be rejected with a 501 Not Implemented status code.
To specify the API method to execute, you need to append it to the end of the URL, as if it were a folder at the given path. For example, if the API method was register_device, the resultant URL would be https://api.quickhac.com/ios/register_device/.
In addition, many API methods require some additional data to do their job. Rather than to pass that through the URL as well, these arguments may be passed as POST parameters.
If a method requires data that was not specified, it will return a HTTP error code 406. If an error occurs during processing, the HTTP code 418 will be returned.
All requests generate some form of return data, which is returned as encoded JSON in the body of the request.
Registers a device with the server, and updates some serverside information. A request to this endpoint should be made from the app delegate's application:didRegisterForRemoteNotificationsWithDeviceToken: function.
- uuid: A unique identifier for the device. This is generated by the app and somehow ties the device to the user.
- status: An integer that is 0 if success, 1 if new registration, and -1 if error.
- lastError: An error code that uniquely identifier the last occurred error.
Adds a HAC username and password combination to the account associated with the device's unique identifier. This information is stored securely in the database and can only be decrypted when combined with unique data from the database.
These credentials, along with the district information, are utilised to fetch the student's grades in a recurring cronjob that queues the notifications.
- uuid: A unique identifier for the device.
- user: HAC username.
- pass: HAC password.
- district: A numeric identifier for the district from the app.
- status: 0 if the addition of this account to the push account was a success, or 1 if it already exists.
If the user no longer wishes to receive push notifications for all students on a specified user account, this method will explicitly destroy all data associated with the account, as well as removing it from the database so no further fetches are performed with it.
- uuid: A unique identifier for the device.
- user: HAC username to locate and remove from the device record.
- status: 0 if the addition of this account to the push account was a success, or 1 if it already exists.
By default, the server does not capture any students when a HAC account is added, so each student that the user wishes to receive push notifications for must be explicitly registered.
- uuid: A unique identifier for the device.
- user: HAC username to add the student ID to.
- id: Student ID of the student that the user wishes to receive notifications for.
- status: 0 if the addition of this account to the push account was a success, or 1 if it already exists.
Removes a given student from the server to stop notifications for it. If all students for a given HAC account are removed, the account itself and associated data is destroyed.
- uuid: A unique identifier for the device.
- user: HAC username to remove the student ID from.
- id: Student ID of the student that the user wishes to remove from the server.
- status: 0 if the removal of this student from the push account was a success, or 1 if an error occurred.