Basic rules

This section described some general rules you should remember while working with API.

Making requests

  • You may call all the services with GET or POST methods (POST preferred).
  • Methods ignore any unknown parameters you supply.
  • CORS requests are allowed. You should not expose your consumer secret though! Keep this in mind if you think on doing OAuth requests with AJAX.

Handling dictionaries

We use dictionaries in many places. We often do this solely because of their "extensibility".

You may not assume, that the same method call will always return the same subset of dictionary keys. More keys might be added in the future, and your application should always ignore such unknown keys.

Handling fields

Many methods allow you to specify which fields are you interested in. Result dictionaries are then filtered based on the selection you specified. There are two things for you to remember though:

  • You may receive more fields (dictionary keys) than you specified.
  • Even if keep receiving such extra fields, you may not expect to receive them in the future, unless you asked for them explicitly.

Signature requirements

There are number of ways you can sign an API request. Some methods require you to sign your request in a specific way, some other may act differently depending on whether you sign or not.

Consumer Key signature might be:

  • required - method requires your application to identify itself,
  • optional - you may identify yourself, in order to achieve some special behavior,
  • ignored - method doesn't care if you sign your request or not.

If you sign with Consumer Key, then you may also include a Token in the signature. It might be:

  • required - method requires you to include a Token. (Usually an Access Token, needed in order to identify the User in whose name you act upon.)

    Note, that if you use an Administrative Consumer Key, then you may use a special as_user_id argument in your request. In this case, you should not include a Token in your signature.

  • optional - you may include a Token, to achieve some special behavior (i.e. some methods allow you to pass user_id - or include an Access Token - both in order to identify a user),
  • ignored - method doesn't care if you include a Token or not.
USOS API ver., 9b190706 (2024-06-10)