Datatypes

This section described some common datatypes the API operates with.

Output formats

Most of the methods come with an optional format parameter. It defines in which format you want the results to be. Currently, there are the following possibilities:

• json - this is the default output format,
• jsonp - this is a JSON-variation which allows you to bypass "same origin policy" with old web browsers; For newer browsers, it is much better to use CORS along with json output format!
• xmlmap2 - if you select this format, then we will simply map all the JSON data types onto XML elements, as shown here,
• We also support two deprecated formats: xmlmap, and xmlitems. Use of these is discouraged, due to inconsistencies present in their implementations (booleans are returned as integers).

Identifiers

There are two types of identifiers in use - integers and strings - but the latter one if strongly preferred. In other words, even when internally we store the objects with integer IDs, we will try to always return the string version of their identifiers. This will help developers to avoid errors, e.g. when searching for an ID inside a JSON dictionary.

You may assume, that all string IDs will be no longer than 32 unicode characters.

Many methods expect pipe-separated lists of IDs in their parameters. You may assume, that no ID will ever contain a pipe ("|") symbol.

Encoding

Each string parameter must be encoded in UTF-8. You may assume that each string contained in a response is encoded in UTF-8 as well.

Fields, subfields and selectors

Most of the methods which return complex objects take the additional fields parameter, that can be used to specify which properties of an object you're interested in. The value of the fields parameter is called a field selector. The most common form of a selector is a pipe-separated list of field names.

Example: id|name|users.

Some of the properties of one object may be represented as other objects, nested into the first one. Such structures are often multiple levels deep. Some methods allow you to use the fields parameter to specify a detailed "map" of such deeply-structured properties. Such selectors are called subfield selectors.

Example: id|name|users[id|email|student_programmes[id]]. In this case, you will get users' programme IDs and email addresses instead of the default first and last names.

Important:

• Not all of the methods recognize subfield selectors in their fields parameters. Some older methods support only the simple selectors.
• Some of the methods may recognize subfield selectors in regard to one field and completely ignore them in regard to some other field.
• Since it is backward-compatible, support for subfield selectors may be added to existing methods and fields without prior notice. To keep your code 100% safe, you should not use subfield selectors in places which currently seem to ignore them.

Language

Most of the data is available in two languages - Polish and English. We use LangDict objects to express data that comes in many languages. LangDict object is simply a dictionary of two keys (pl and en) and their values (strings, might be empty).

When passing LangDict as an argument you have two choices:

• serialize the object and pass it directly using argument name;
• submit each object member as a separate argument with language suffix (*_pl or *_en).

In most cases you don't have to provide both pl and en keys. Unless otherwise specified, methods that create objects interpret missing key as an empty string and methods that update objects don't modify previous value.

Date and time

There is no native representation of date and time in JSON. We use our own datatypes for input and output of dates.

• date string - a string in the "yyyy-mm-dd" format,
• time string - a string in the "hh:mm:ss" format,
• datetime string - combination of date and time strings, separated with space ("yyyy-mm-dd hh:mm:ss").

We always use local time. If your application cares about time zones or daylight saving, you will have to deal with the conversions on your own.

Files

Passing files as method arguments imposes several restrictions on the request:

• the request body must be encoded as multipart/form-data;
• only PLAINTEXT signature method is supported; you MUST use SSL in order to keep your consumer secret safe.

Partial responses

Many methods return multiple objects, explicitly referenced by multiple keys you provide.

Usually, invalid references will be treated as an error. For example, when you ask for course descriptions of 30 different courses, and one of these courses does not exist, you will get the HTTP 400 error. Partial responses allow you to retrieve 29 of 30 referenced courses.

Methods which implement partial responses expose the partial parameter. If you set it to true, then the whole of the response will be wrapped with an additional Partial Response object:

• success - true if there were no errors (invalid references),
• partial_response - original value returned by the method (format may vary, usually this will be a dictionary of referenced objects' keys with corresponding objects),
• unexistent_keys - a list of keys, which couldn't be found and will not be included in the response.