Accessing USOS API server data
:: services/apisrv module

These API methods allow you to access information on the USOS API server installation, and also retrieve some basic data on all the other official USOS API installations.

Methods

consumer Get information on the Consumer.
installation Get information on this USOS API installation.
installations Get a list of all public USOS API installations.
now Get current USOS API time.

services/apisrv/consumer

Consumer: required Token: optional Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/apisrv/consumer

Get information on the Consumer.

Currently, you can use this method only to get information on a single Consumer - yourself. Simply sign your request with OAuth in order to verify who you are. You may also pass an Access Token along to get some extra information on the permissions granted to you by the user.

Important: You are allowed to call this method via the proxy method, but only the token_scopes field will be available (provided that your proxy is signing requests with Access Tokens, if it is not, then you will get null). Make sure you're asking only for the token_scopes field, otherwise you will get an error.
fields required Pipe-separated list of fields you're interested with.
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 of fields you have asked for. Available fields are:

  • name - the application name you have provided when you have registered for your Consumer Key,
  • url - the application URL which you have provided when you have registered for your Consumer Key or null if you didn't provide any,
  • email - the email address you have provided when you have registered for your Consumer Key,
  • date_registered - datetime string, the date when you have registered your Consumer Key,
  • administrative_methods - the list of names of USOS API methods you've been granted administrative access to,
  • token_scopes - the list of scopes which the user have granted you access to or null if you didn't provide an Access Token with your request.

services/apisrv/installation

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/apisrv/installation

Get some basic information on this USOS API installation.
fields optional

Default value: base_url|version|machine_version|usos_schema_version|institution_name|contact_emails

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.
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • base_url - base URL of this installation.

    For backward compatibility, this will always start with the "http://" protocol. You should use "https://" in your method calls though!

  • version - a "version string" of this USOS API installation.

    The structure of this string is undocumented. It may contain anything (e.g. an information that the version is unknown). It is designed to be understood by humans, not machines. Compare this to machine_version field.

    Some possible values (this may change in time!):

    • 5.2.0.0-3, 63432a1 (2012-07-03)
    • 5.2.0.0-3 (2012-07-03)
    • 5.2.0.0-3, 63432a1, dirty
    • 5.2.0.0-unknown

  • machine_version - machine-readable version, in 0.0.0.0-0 format.

    This value is suitable to be read by machines. We can guarantee that it matches the following regular expression: [0-9]+\.[0-9]+\.[0-9]+\.[0-9]+-[0-9]+ (for example "6.2.10.0-13"). This string won't always be as accurate as the one in the version field, but it will be supplied in a documented and backward-compatible way, thus allowing an easy way of feature-detection for external applications.

    You may assume that if a non-beta feature is implemented in version X, then the same feature will also work (in backward-compatible manner) on all versions higher than X. Keep in mind that you need to use a customized comparison method for these strings (it is invalid to compare versions strings lexicographically).

    We cannot guarantee that all USOS API versions will come in this format in the future, but we do guarantee that this field will always return values in this particular format. If USOS API switches its versioning scheme, then this field will get deprecated, and simply keep returning the version string matching the last of the USOS API versions which has been released in this format.

  • usos_schema_version - version string of the USOS database used by this installation;

  • institution_name - a LangDict object with the name of the institution which is the owner of this installation, or null if it is unknown;

  • institution - the "primary" faculty object.

    This will contain a single selected faculty object, as described in the services/fac/faculty method. This primary institution faculty is also often a common ancestor of most of the faculties is the faculty forest (but sometimes it is not).

  • contact_emails - a list of strings, email addresses of local USOS API administrators.;

  • schac_id - unique institution ID in SCHAC format.

    SCHAC ID consists of the primary institution domain name, stripped of any "www." prefixes, etc.

  • mcards_support - True if mCards (mLegitymacje) are supported.

services/apisrv/installations

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/apisrv/installations

Get a list of all public USOS API installation servers (including this one).

There are many institutions that use USOS API. Each of them has it's own database and it's own USOS API server. This method allows you to access a list of all public USOS API servers.
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 list of dictionaries, each dictionary in of the same structure that the one returned in the installation method, but the number of fields is limited to the following:

  • base_url
  • version
  • institution_name
  • contact_emails

services/apisrv/now

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/apisrv/now
Get the current USOS API time. Your application might call it periodically in order to determine time offset of our clocks. Exact timing matters in some cases (like when a registration starts).
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 DateTime string (first 19 characters), followed by a dot and a 6-digit fractional part of a second ("yyyy-mm-dd hh:mm:ss.dddddd"). This represents the current USOS API server local time (all DateTime strings API methods return are in local time, unless stated otherwise).
USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)