USOS API Installations

Key facts:

  • There are multiple USOS API installations. Each university/institution has their own installation.
  • Each installation issues its own Consumer Keys.
  • There is one additional USOS API installation, unbound to any institution. It is called the mother server and it is reserved for internal use (see below for details).

Single-target or Multi-target Architecture

First you have to choose whether:

  • You want your application to interact with data of one, single institution, or
  • You want your application to interact with many institutions at the same time.

This is an important design decision as it might influence the entire structure of your application.

Regardless of what you choose, we advise you to NOT "hardcode" absolute API method URLs in your application. Use an usosapi_base_url variable as a prefix and simply append service names to that variable (and replace "http://" with "https://" in case of some methods). This way, your application might be easily copied and run on other USOS API installations in future.

Notes on Multi-target Architecture

USOS API installations might differ slightly. This is due to the USOS system distrubution requirements (each institution might have different versions of the USOS system).

If you plan to connect to multiple installations, it might be better to use the oldest (lowest version number) USOS API installation as the documentation reference. It will let you avoid some misassumptions.

You can use the services/apisrv/installations method to retrieve the current list all installations. You might, for example, periodically check it against the list of installations your application supports, and notify yourself if there is a new one (then, you can generate a new API key and include it in your application).

And remember, that all the data (even when available anonymously) is copyrighted.

What's a mother server?

The mother server is a "special" USOS API installation.

  • There's only one USOS API mother server: http://apps.usos.edu.pl/.
  • It is visible to all the search engines, but it is not intended to be used for calling methods.
  • You cannot register a Consumer Key in the mother server.
  • You should not call any API methods on the mother server without consulting USOS API developers. Even if the method can be called anonymously.
  • The mother server may contain more recent documentation than any of the other servers. You may use it to take a "sneak peek" at new features.

Why mother server exists?

  • The mother server is used as a central synchronization server between all the other USOS API installations. I.e. it provides other USOS API servers with the data needed to "discover" each other.
  • In the future, we may also use the mother server's domain to serve some extra content related to USOS API in general (and unrelated to the specific USOS API installation). For example, the USOS API blog.

Current installations

USOS API is currently running on the following USOS installations:
USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)