Accessing API documentation
:: services/apiref module

These API methods allow you to access the documentation on the API itself.

Seems a bit weird, huh? ;) Actually, here are some quite interesting usecases for you to consider. If you decide to give them a try - let us know! We might want your solutions to be incorporated into our project. :)

apiref module allows you to:

  • Automatically generate up-to-date USOS API client libraries in various programming languages.
  • Generate API documentation in various formats.
  • Design an alternate version of USOS API Reference web site (for example, with AJAX and JSONP).
  • Design a sandbox allowing people to explore and play with various API methods.

Methods

method Get information on a given USOS API method.
method_index Get a list of USOS API methods with brief descriptions.
module Get information on a given USOS API module.
scopes Get a list of all available scopes.

services/apiref/method

Consumer: optional Token: ignored Scopes: n/a SSL: not required
https://appsusos.uek.krakow.pl/services/apiref/method
Get information on a given USOS API method.
name required Name of a method (begins with "services/").
fields optional

Default value: (most of them)

Pipe-separated list of fields which you are interested in.

Initially, this method did not take the fields parameter. That's why, for backwards compatibility, all the fields which were exposed by this method before the fields parameter was added, are now also included by default.
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 optional 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 of requested fields. Allowed fields include:

  • name - name of the method,
  • short_name - name without a path,
  • description - HTML-formatted description of what the method does,
  • brief_description - brief (max 80 characters), single-line, plain-text description of what the method does,
  • ref_url - URL of a USOSap Reference webpage with method description,
  • auth_options - a dictionary which describes authentication requirements for this method, it has a following structure:
    • consumer - "required", "optional", "ignored",
    • token - "required", "optional", "ignored",
    • administrative_only - boolean, indicates if method is available for Administrative Consumers only,
    • ssl_required - boolean, indicates if secure connection required to call this method (if it is, then just switch http to https).
    • scopes - a list of strings, scope identifiers, which you need to have access to in order to run the method.
  • arguments - list of dictionaries describing method's parameters. Each dictionary has a following structure:
    • name - name of a parameter,
    • is_required - boolean, true if the parameter is required,
    • is_deprecated - boolean, true if the parameter is deprecated,
    • default_value - default value of the parameter or null if parameter doesn't have a default value,
    • description - HTML-formatted description of a parameter.
  • returns - HTML-formatted description method's return value.
  • errors - HTML-formatted description of possible method exceptions.

  • result_fields - list of method's result fields. Any field can belong to either primary or secondary section. This list serves as a concrete specification and an alternative for the "returns" field in the method description. Each element of that list has a following structure:

    • name
    • description
    • is_primary - True if field is in primary section.
    • is_secondary - True if field is in secondary section.
  • beta - true if this method has a BETA status. BETA methods may be altered in a backward-incompatible way.

  • deprecated - in case of non-deprecated methods this will be null. In case of deprecated methods, this will be a dictionary of the following structure:

    • deprecated_by - method that should be used instead of this one or null if the user should consult the documentation,
    • present_until - if not null, then the method is scheduled to be removed at the given time (this is a string in any format, not necessarily a date!).

  • admin_access - true if you have administrative access to this method.

    You need to sign the request with your Consumer Key in order to access this field.

  • is_internal - true if this method is intended to be used only internally, by USOS API itself. This implies that it is in permanent BETA mode, and it can be altered or removed at any time.

services/apiref/method_index

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://appsusos.uek.krakow.pl/services/apiref/method_index
Get a list of USOS API methods with brief descriptions.
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 of which contains one API method description in the following format:
  • name - name of a method,
  • brief_description - plain-text, brief (usually single sentenced) description of what the method does.

services/apiref/module

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://appsusos.uek.krakow.pl/services/apiref/module

Get information on a given USOS API module.

Modules are like folders - they group methods and other modules related to one topic.
name required Name of a module (begins with "services/").
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:
  • name - name of the module,
  • title - title of the module,
  • brief_description - currently, this is an even briefer version of the title (the name of the field is misleading, as it currently does NOT contain a description, but it might in the future),
  • description - HTML-formatted description of module topics and contents,
  • submodules - list of (fully-qualified) names of modules enclosed within this module,
  • methods - list of (fully-qualified) names of methods enclosed within this module.
  • beta - True if module is beta (Some methods in module may be changed (backward incompatible).

services/apiref/scopes

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://appsusos.uek.krakow.pl/services/apiref/scopes

Get a list of all scopes which are available in this USOS API installation.

Note, that if you want to determine if a specific installation supports some functionality, you may also refer to its version string (see services/apisrv/installations 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.
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A list od dictionaries, each of the following structure:
  • key - a key (code) of a scope,
  • developers_description - HTML formatted, developer-oriented description of the scope ("Provides access to...").
USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)