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.

Methods

notifier_status BETA Get information on the status of the notifier.
subscribe_event BETA Subscribe to events.
subscriptions BETA Lists your (the consumer) subscriptions.
unsubscribe BETA Unsubscribe from events.

services/events/notifier_status

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. 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 method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Get information on the status of the notifier.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary of the following structure:

  • daemon_running - true if notification sending daemon is running correctly, false otherwise,
  • total_pending_events_count - number of all unprocessed events in the queue.

services/events/subscribe_event

Consumer: required Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. 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 method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Subscribe to events of a given type. Please refer to module documentation for detailed explanation of entire subscriptions and notifications flow. You can call this method only once every minute for a given event type (unless you have administrative access to this method).
event_type required The type of event that you want to subscribe.

Possible values: crstests/user_grade, grades/grade, crstests/user_point.

callback_url required The URL of your server. The notifications will be sent to this URL as events occur.
verify_token optional The string that will be passed as an additional query parameter to your URL during the verification.
format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

Dictionary with only one key: id, its value being the ID of newly created subscription.

Thrown errors:

  • method_forbidden - access to method denied.

    Possible reasons:

    • too_many_subscription_requests - You need to wait before you make another subscription request.

  • object_invalid - object is in invalid state.

    Possible reasons:

    • subscription_duplicated - A subscription for this consumer and event type already exists.

  • param_invalid - parameter has invalid value.

    Possible reasons:

    • failed_challenge - Callback URL failed challenge;

    • request_timeout - Didn't get a response for challenge request in time.

services/events/subscriptions

Consumer: required Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. 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 method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Lists your (the consumer) subscriptions.

fields optional

Default value: id|event_type|callback_url

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

A list of subscriptions as dictionaries with selected fields and their values.

Available fields of subscription dictionary:

  • id - the ID of a subscription;

  • event_type - the event type of a subscription;

  • callback_url - the callback URL of a subscription.

services/events/unsubscribe

Consumer: required Token: ignored Scopes: n/a SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

This is a BETA method. 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 method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Unsubscribe from events. The parameters you pass to this method form a filter. This filter will be used to search your (the consumer) subscriptions. The ones that match will be deleted.
id optional The ID of a subscription.
event_type optional The event type of a subscription.
callback_url optional The callback URL of a subscription.
format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

Empty dictionary.

Thrown errors:

  • object_not_found - some of the referenced objects do not exist.

    Possible reasons:

    • subscriptions_not_found - There are no subscriptions matching criteria.

USOS API ver. 6.1.2.0-bc1aa53 (2016-06-07)