PrevUpHomeNext

API State

The Timetable Generator API is a stateful API; that is, the API manages state information and remembers it between calls to API functions. As a result, what an API function does may depend on what other API functions have been called before.

Two central concepts in the API are those of a user session, or session for short (not to be confused with a 'study session'), and a course load. A user session represents the interaction of a user with the API in one sitting (by "user", I mean for example a user of a web service whose web server is powered by this API; a desktop application powered by this API would only have one user session). Over the course of a user session, a user may interact with one or more course loads. Examples of interactions with a course load include selecting the courses that make up the course load, generating timetables for those courses, viewing those timetables, and sorting those timetables by the number of days off. A user session can involve interacting with more than one course load in sequence (for example, the user can close a course load and open a new one instead) or in parallel (API clients that support this are said to have a multiple document interface). On the other hand, if the user saves their timetables and then later comes back to look at them, then the initial generation and saving of the timetables, and the later looking at them, constitute two separate sessions.

The API maintains two types of state: global state, which is shared by all user sessions, and per-session state, which is specific to a particular user session.

The global state managed by the API consists of information about the study sessions that the API knows about, and information about the courses available for each study session (including the offerings for each course, the meetings and meeting sections for each offering, the timeslots for each meeting section, and so on). The API persists this information to a set of internal data files (see Data Files Used by the API). It is capable of updating this information by downloading updated data from the University of Toronto's website, and of importing this information into its internal data files from another source (in the appropriate format).

The per-session state managed by the API consists of information about one or more course loads and information associated with them, such as selected configurations and generated timetables.

Given these two types of state, the API functions can be classified into three categories:


PrevUpHomeNext