Accessing and modifying user preferences
:: services/uprefs module

This module presents user preferences as a simple structure of a multilevel tree, with well-defined UI components in its leafs. We believe that this simple model will be enough to express most of the user preferences we are about to support in the years to come.

There are a couple of things you should be aware of before you consider using this module:

  • Backward-compatibility. The interface of this module is designed to be backward compatible. However, the preferences themselves are not supposed to stay backward compatible. Some preferences will be dropped in the future, others will be replaced with other preferences. You cannot rely on undocumented preference IDs neither to exist nor to "keep their meaning" indefinitely. You should avoid hardcoding preference IDs in your application (unless its a predefined ID, see below).

  • Effective preferences. For some types preferences, we will be exposing separate methods for you to access their "effective value". As long as you don't want to change the preferences - you should most probably be looking for those! They can be found in other modules, not necessarily in this one.

    What exactly do we mean by "effective value"? Say, if user A doesn't want user B to view his/her photo, we will simply return null (or something similar) when you ask for the photo of user A using the Access Token of the user B. In other words, you don't have to even know about the existence of the preference, USOS API will properly "hide" the values for you. Be cautious with administrative access though! You might need to use the services/oauth/proxy method in order for effective values to work as you'd expect.

  • Visibility. Preferences are generated dynamically, based on many variables. Every consumer, and/or every user may "see" a different set of preferences. In particular, some preferences may be hidden (or disabled) if you don't have access to the proper scopes.

Methods

change_preference Change the value of a preference.
preference Get information on a given preference (or group).
preferences Get information on multiple preferences.
values Fetch the values of a single preference for multiple users. (administrative)

services/uprefs/change_preference

Consumer: required Token: required Scopes: change_all_preferences SSL: not required
https://apps.usos.uj.edu.pl/services/uprefs/change_preference

Change the value of a preference.
upref_id required Preference ID. (This has to be a non-group-type preference.)
value required

The new value of the preference.

For boolean (checkbox) preferences use "true" or "false".
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. Plus required oauth_token for Token authorization.

Returned value:

{"success": true}

In case of failure, use the user_messages field to display a proper message for the user.

services/uprefs/preference

Consumer: required Token: required Scopes: none SSL: not required
https://apps.usos.uj.edu.pl/services/uprefs/preference

Get information on a given preference (or group).
upref_id required

ID of the user preference (or group of preferences).

Most of the IDs are not backward-compatible. They may either disappear or change their type or meaning at any time. You should not hardcode any of these IDs in your code, unless it is a predefined ID:

  • root - use this ID if you want to access the tree of all available preferences,
  • photo_visibility - the subtree of preferences regarding visibility of the user's photo,
  • email_privacy_root - the subtree of preferences regarding the privacy ad visibility of the user's email address,
fields required

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

preferred_types optional

Default value: (empty string)

Pipe-separated list of preference types which you are able to display properly. See the "returns" section for current list of types.

In time, we will be adding more preference types. Some of them might be quite complex. However, many preferences might still be expressed using the "legacy" types, e.g. textboxes or checkboxes. If we know that you don't support some new types of preferences, we may choose to convert them to the "legacy" types, supported by you.

This parameter is optional, but recommended. If you don't supply this value, we will currently assume that you can understand every preference we can think of.

Keep in mind, that these are only preferred types. This means that we may still include unknown types in the response and you must ignore preferences with such unknown types.
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. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - the ID of the preference (or group of preferences);

  • type - type of the preference.

    One of the following values:

    • textbox - such preferences should be rendered as textboxes. The type of their value is a string.
    • checkbox - such preferences should be rendered as checkboxes. The type of their value is boolean.
    • list - such preferences should be rendered using a radiobox or other similar component. The type of their value is a string and the possible values are presented in the list_items field.
    • group - a group of preferences. Preferences can be nested within groups (e.g. pages, tabs, sections, dialogs). The group-type preferences are inner nodes within the preferences tree. Such nodes have no value (it will be always null), instead they have a list of entries.
    • Other types will come in the future! Some of these types might be quite complex and may require you to design your own specialized components. You should ignore preferences with types unknown to you.

  • title - A LangDict object. A short title for the preference (in plaintext);

  • summary - A LangDict object, or null if empty.

    If given, it will be a short description of the preference - usually one or two sentences in a single paragraph. May contain simple HTML markup and links to external resources.

    Important: Some summaries may change based on the values of their own preference and/or other preferences. It is important that you refresh the values of these fields every time the user changes any preference via your UI. (This also means that we require the user interface to "live" - i.e. you should not require your users to click any "save" buttons).

  • enabled - boolean, indicates if the user can change this preference.

    Important: Similar as above, some preferences might get disabled or enabled based on other preferences. You must refresh these fields every time the user changes any preference via your UI!

  • value - the current value of the preference.

    The format of this field varies on the preference type. See the description of the type field for more information.

  • list_items - items to display on a list preference.

    This field is not-null only for preferences of the list type.

    A list of dictionaries. Each dictionary has the following keys:

    • value - the value of the item. One of the values in list_items will always match the current value of the preference (the one in the value field). This is the internal value of the preference and should not be displayed to the user.
    • title - a LangDict object, the name of the item to be displayed for the user, in plaintext.
    • summary - a LangDict object, additional information on the item. One paragraph with one or two sentences. May contain simple HTML markup.

  • entries - the list of preferences within the group, or null if it is not a group.

    This is simply the list of preference objects. Each object is of the same type as the object described in the method that you're now reading.

    If no subfield selector is given, each entry will contain the same fields which you have asked for in your fields parameter, including the entries field. This allows you to access the entire subtree of preferences recursively.

    This field references objects returned by preference method. See its returns section for possible subfields.

services/uprefs/preferences

Consumer: required Token: optional Scopes: n/a SSL: not required
https://apps.usos.uj.edu.pl/services/uprefs/preferences

Get information on multiple preferences.
upref_ids required Pipe-separated list of preference IDs.
fields required

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

preferred_types optional

Default value: (empty string)

Same as in the preference method.
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. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary: your upref_ids will be mapped to dictionary's keys, and each value will contain the description of one preference, as defined in the preference method.

services/uprefs/values

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://apps.usos.uj.edu.pl/services/uprefs/values

This method allows you to retrieve current values of a single preference for multiple users. Only some preferences can be fetched this way.

Important: Since preference IDs are not backward compatible, this method should be avoided! It is intended to be used primarily from within USOS API itself, in order to properly determine the effective outcomes, which are later exposed in other, specialized methods. Before you use this method, make sure no such specialized methods exist, you may also contact us and we may provide such specialized methods for you.
upref_id required ID of the preference. Only some preferences can be fetched using this method. If the given preference ID is not supported, then you will get a HTTP 400 response.
user_ids required Pipe-separated list of user IDs. They must be valid user IDs, if they're not, then the results are undetermined - you may get an error, but you may also get fake/invalid values.
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 dictionary: your user_ids will be mapped to dictionary's keys, and each value will contain the current value of the preference, as defined in the value field in the preference method.

If the given preference is unknown or not supported, then you will get a HTTP 400 response.
USOS API ver. 7.1.0.0-3, fb388208, dirty (2024-08-19)