Events

:: services/events module

This is a BETA module. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this module, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Methods in this module allow you - the developer of application that utilizes USOS API - to manage subscriptions of events. You can think about event subscription as a promise that USOS API will notify you when the event that you are subscribed to occurs.

The standard usage example involves a scenario when an impatient user of your application has to manually refresh data every few minutes in order to check whether his grades have been updated. With events module you will be able to subscribe to grades/grade event, get notified about grade updates in real time and use this information for notifying the user about the data change as soon as possible.

In order to receive notifications from USOS API, you will need a publicly available server. The notifications will be sent as JSON data in body of HTTP requests from USOS API to your server.

Here is the overview of entire subscription and notification process. Detailed explanations for all steps follow.

1. Choose the type of event that you want to subscribe.
2. You subscribe to a given type of events through subscribe_event method. Aside from the type of event, you need to provide a URL to your server - the endpoint that will receive notifications.
3. Your request is validated. Providing the validation was successful, a new subscription is created for you.
4. Assume that an event of the type you chose in step 1 occured.
5. USOS API checks your permissions to receive the notification (if needed).
6. Your server receives an HTTP request with one or more notifications.

Step 1. In USOS API, some of the methods allow you to retrieve single entity records - for instance, the services/grades/grade method returns you a single "grade" entity record. Such methods are named after entities they return. Event types are paths to such methods. A path to a method consists of module name and method name, so the path for the services/grades/grade method is grades/grade. Thus, you can use grades/grade event type to subscribe to modifications related to "grade" entity records.

Step 2. As you will notice in the documentation for subscribe_event method, you need to sign the requests to this method with your consumer key. This is because subscriptions are created in context of consumer (application). Typically, you will create a subscription during application development. Note that you only need to create one subscription for one event type per application (this is validated during step 3) - not one per application instance.

Step 3. First, we need to make sure that you are in fact under control of the server described by the URL you provided in step 2. In order to do this, USOS API performs a check very similar to one described in PubSubHubbub protocol. An HTTP request to your URL is made with some additional parameters attached:

• hub.mode with value subscribe,
• hub.challenge with value being randomly generated string,
• (optional) hub.verify_token with value that you provided in step 2 (only if you provided it, naturally).

To pass this test, your server must reply in time allowed with hub.challenge query parameter value. It must be the sole content of the response. The hub.verify_token, if provided, can be used by you to make sure that you are in fact handling a request from USOS API, triggered by your subscription request.

There is also a second check: duplication. One consumer cannot have more than one subscription for a given event type.

Step 4. USOS API receives information about events from two kinds of sources: internal systems and event triggering methods. There is one such method for every event type. The naming convention for these methods is {entity}_modified. Example: services/grades/grade_modified method from grades module.

Step 5. Due to sensitive nature of information that USOS API provides, before we push any notifications to your server, we need to make sure that you are allowed to receive it. This applies only to event types related to sensitive data. The rule of thumb is: if the USOS API method derived from event type (remember, event types are in fact paths to methods - see detailed explanation for step 1) requires you to provide an access token in context of some user - then in order to receive notification of that event type, containing information about that user, you must have a valid token with appropriate scopes (as defined by derived method) for that user, or have administrative access to derived method. If, at the moment of event, you do not have any of these, then you simply will not receive the notification. Since events can occur at anytime, it is highly recommended for you to ask for offline_access scope from your users if you plan to subscribe to user data sensitive notifications, as tokens with this scope do not expire (unless user revokes access to his data from your application).

Step 6. As mentioned, the notifications are delivered to your server in a body of HTTP request. The request method is POST. The request body is in JSON format and contains a dictionary with two fields:

• event_type: a string being the event type of events that caused the notifications from this request,
• entry: a list of notifications in JSON format; one request can contain up to a thousand of them. As you can tell from event_type description above, all notifications that come in a single request were caused by events of the same type, thus they have same structure.

The exact format of a single notification varies between event types, but is always quite similar. You can expect the following fields and values:

• time: an integer being the UNIX time of event in UTC,
• (optional) related_user_ids: if the event is in context of one or more users (that is, when you need an access token to call the method derived from event type), this will be a list of strings; it will contain either one element, "*", meaning the event is related to all possible users, or one or more elements being IDs of users related to event,
• remaining fields: to find out about remaining fields, find the method used for triggering the given event type (see detailed explanation for step 4); the remaining fields of the notification are same as the required parameters for this method (note that this method might have related_user_ids parameter; this field has already been described above because its meaning is a little more complex than what description of the method might suggest).

Here is a sample HTTP request body matching the rules described above.

{
  "event_type": "grades/grade",
  "entry": [
    {
      "time": 1381951223,
      "related_user_ids": [
        "123456"
      ],
      "operation": "create",
      "exam_id": "1",
      "exam_session_number": 2
    }, {
      "time": 1381951225,
      "related_user_ids": [
        "543211"
      ],
      "operation": "update",
      "exam_id": "5",
      "exam_session_number": 10
    }
  ]
}

The operation, exam_id, exam_session_number and related_user_ids fields of notifications in the example above are derived from required parameters of services/grades/grade_modified method in grades module.

Note that there is (almost) no sensitive data being sent in the notification; the notification itself is only an "invitation" to get the updated, actual data through calling the method derived from event type (with appropriate access token if needed). This is due to security reasons.

The request to your server will also contain an additional X-Hub-Signature header. Its value will be sha1={checksum}, the {checksum} being HMAC SHA1 signature of request body, with secret key of consumer used to create subscription used as a key.

Your server should be able to handle requests from USOS API in a timely manner. Redirects are not allowed. There are no retries if something goes wrong. If your server frequently fails to respond to requests, your subscriptions may be removed. Also, we cannot guarantee you that every notification that should be sent to you, will in fact be sent. The odds that it will though are very, very high.