This section described some common datatypes the API operates with.
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:
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.
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.
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.
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:
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.
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.
Passing files as method arguments imposes several restrictions on the request:
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: