Versions Compared

Old Version 88

changes.mady.by.user Former user

Saved on

compared with

New Version 89

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add links property to /timetable & /timetable/{key} API responses

Table of Contents

Introduction 

...

NameDescription
activityDescriptionThe description of the activity, could be the course, module or activity name. This should be shown to the user as 'main description'.
moduleCodeSome customers have a separate module code available which is a (semi-) unique identifier for a certain course of module.
activityTypeNameThe name of the activity type this event belongs to. Key value which can be used to group and colour activities. Should not be shown to the end-user directly.
activityTypeDescriptionThe description of the activity type of this event. This value should be shown to the user and indicates whether the activity is a lecture, practical, exam, etc. Not all institutions provide (sensible) activity type information.
startDateStart date and time of the event. See below for the date format.
endDateEnd date and time of the event. See below for the date format.
studentSetsList of student sets (e.g., classes, groups) associated with the event.
locationsList of locations associated with the event (consists of identifier, name, key, capacity, url and avoidConcurrencyLocationIds (MyTimetable v2.5+, list of id's of locations that are also occupied if this location is occupied)).
staffMembersList of staff members associated with the event.
notesSome notes or additional information about the event, not all customers use this field.

timetableKeys

Contains the list of subscriptions (timetables) this event is part of (MyTimetable v2.5+)
highlightedTrue iff the event should be highlighted in the interface (reason is customer or department specific) (MyTimetable v2.5+)
tagsList of tags assigned to the event (MyTimetable 2.7+)
linksList of links assigned to the event (MyTimetable 3.10+)

New fields may be added to objects without incrementing the version number. See 3114172430API Documentation for details.

Input and output format

...

Input can be provided in the form of HTTP GET URL parameters (which should be URL encoded properly) or an HTTP POST/PUT body that is in application/x-www-form-urlencoded. Most parameters are optional, when this is not the case this is mentioned in the documentation. Dates and times can be specified in one of the following format:

  • 'today' or 'tomorrow' for the current or next day at 0:00;
  • Unix timestamp format (in milliseconds sinds 1970, so don't forget to multiply/divide by 1000);
  • ISO 8601 format (yyyy-MM-ddTHH:mm:ss±HH:mm): elements on the right side (time, time zone) are optional;
  • Legacy format (yyyy/MM/dd HH:mm): the time is optional.

Authentication and authorisation

...

Multiple datasources with timetabling data may be available (e.g., when retrieving data from multiple years). By specifying a GET parameter d, it is possible to select a certain database for the request in certain requests. The list of possible databases can be retrieved with the 3114172430API Documentation call. If no database is specified, the default database will be used, which is usually the most sensible option. For older MyTimetable versions (<v2.4) it is necessary to select the right database with every call, if not using the default database.

...

Description: Query all possible timetable types, these types serve as input for the /timetables, /timetable and /timetablefilters calls. See 3114172430API Documentation for a discussion on the meaning of the types. MyTimetable versions before v2.3 return all possible types supported by the back-end, in that case consult Customer-specific API information to find out what types the customer uses. 

...

Code Block
languagenone
{
    "timetableType": [
        "location", 
        "zone", 
        "module", 
        "student", 
        "staff", 
        "pos", 
        "posss", 
        "studentset", 
        "studentsetgroup", 
        "modulegroup", 
        "user",
		"tag"
    ]
}

/timetabletypesdetails   (since MyTimetable 3.0)

Method: GET

Description: Query all possible timetable types and return them including some details regards naming, whether or not they can include child timetables and their ordering in the menus. 

...

Code Block
languagenone
[
    {
        "activityDescription": "Tsjechische letterkunde 2",
        "activityTypeColor": "#0000ff",
        "activityTypeDescription": "Werkcollege",
        "activityTypeName": "Werkcollege",
        "allDay": false,
		"conference": false,
        "conferenceUrl": null,
        "customAttributes": {},
        "department": {
            "id": "2010!1E65DFEB58C56AAF042109ECF86B3149",
            "name": "Department of Languages"
        },
        "draft": false,
        "endDate": 1355320800000,
        "enrolled": null,
        "eventType": {
            "color": "#0000ff",
            "description": "Lecture",
            "eventTypeGroup": {
                "description": "Group Session",
                "id": "Group Session"
            },
            "id": "lecture"
        },
        "filtered": false,
        "highlighted": false,
        "locations": [
            {
                "avoidConcurrencyLocationIds": [],
				"bookUrl": null,
                "capacity": 118,
                "customAttributes": {},
                "examCapacity": null,
                "capacity": 16,
                "customAttributes": {},
                "id": "492E26C5A6F3BDE74C11240C046C3257",
                "key": "908K04SEM1",
                "name": "Bungehuis K.04",
                "sipAddress": null,
                "url": null
            }
        ],
        "moduleCode": "UvA/FGW/TLK_133214266",
        "notes": "Group 14 only",
        "notes2": "",
        "notes3": "",
        "recorded": false,
        "recordingUrl": null,
        "staffMembers": [
            "dr. E.R.G. Metz"
        ],
        "startDate": 1355313600000,
        "students": [],
        "studentSets": [],
		"tags": [
            {
                "key": "weblecture", 
                "name": "Web Lecture"
            }
        ],
		"links": [],
        "timetableKeys": [
            "2010!module!40B7FB6233A4AD9834C7B999276851F5"
        ]
    }
]

/timetables/{key}/options    (since MyTimetable 3.1)

Method: GET

Description: Query the available options for the specified timetable. These options can be set on the subscription using the PUT call on a subscription. The allEquivalent boolean in the output will be true if any choice of options results in the same timetable.

...

/timetables/{parent}/{key}/options    (since MyTimetable 3.1)

Method: GET

Description: Query the available options for the specified child of a timetable. These options can be set on the subscription using the PUT call on a subscription. The allEquivalent boolean in the output will be true if any choice of options results in the same timetable.

...

Code Block
languagenone
[
    {
        "activityDescription": "Tsjechische letterkunde 2",
        "activityTypeColor": "#0000ff",
        "activityTypeDescription": "Werkcollege",
        "activityTypeName": "Werkcollege",
        "allDay": false,
		"conference": false,
        "conferenceUrl": null,
        "customAttributes": {},
        "department": {
            "id": "2010!1E65DFEB58C56AAF042109ECF86B3149",
            "name": "Department of Languages"
        },
        "draft": false,
        "endDate": 1355320800000,
        "enrolled": null,
        "eventType": {
            "color": "#0000ff",
            "description": "Lecture",
            "eventTypeGroup": {
                "description": "Group Session",
                "id": "Group Session"
            },
            "id": "lecture"
        },

        "filtered": false,
        "highlighted": false,
        "locations": [
            {
                "avoidConcurrencyLocationIds": [],
				"bookUrl": null,
                "capacity": 118,
                "customAttributes": {},
                "examCapacity": null,
                "capacity": 16,
                "customAttributes": {},
                "id": "492E26C5A6F3BDE74C11240C046C3257",
                "key": "908K04SEM1",
                "name": "Bungehuis K.04",
                "sipAddress": null,
                "url": null
            }
        ],
        "moduleCode": "UvA/FGW/TLK_133214266",
        "notes": "Group 14 only",
        "notes2": "",
        "notes3": "",
        "recorded": false,
        "recordingUrl": null,
        "staffMembers": [
            "dr. E.R.G. Metz"
        ],
        "startDate": 1355313600000,
        "students": [],
        "studentSets": [],
		"tags": [
            {
                "key": "weblecture", 
                "name": "Web Lecture"
            }
        ],
		"links": [],
        "timetableKeys": [
            "2010!module!40B7FB6233A4AD9834C7B999276851F5"
        ]
    }
]

...

/subscriptions/{key}/options     (since MyTimetable 3.1)

Method: PUT

Description: Set selected options of a subscription. Specifying all possible options will cause the list of selected options to be cleared, showing the complete timetable to the user.

...

/subscriptions/{parent}/{key}/options     (since MyTimetable 3.1)

Method: PUT

Description: Set selected options of a subscription nested under a parent. Specifying all possible options will cause the list of selected options to be cleared, showing the complete timetable to the user.

...

Code Block
languagenone
{
    "feedUrl": "http://myuniversity/ical?eu=FKW92Fawier&t=556cf8a1-704a-4997-bc4d-5acf395eccaf",
    "username": "testuser",
    "roles": [
        "ROLE_STUDENT",
        "ROLE_MEMBER"
    ]
}

/weeklabels   (deprecated since MyTimetable 2.7, replaced by: /weeklabelmaps)

Method: GET

Description: Query the weeklabels. This provides custom labels for the weeks when available. The response includes a value (the custom label) and a week (year - 1900 + the ISO week number).

...

Code Block
languagejs
{
    weeklabel: [
        {
            "week": 11223,
            "value": "23"
        },
        {
            "week": 11224,
            "value": "24"
        }
    ]
}

/weeklabelmaps   (since MyTimetable 2.7)

Method: GET

Description: Query the weeklabel maps. This provides the available maps with custom labels for the weeks. Per weeklabel map, the response includes a key and a boolean which indicates whether the map is the default weeklabel map for the requested user.

...

Code Block
languagejs
{
    "weeklabelmaps": [
        {
            "key": "SYLLABUS",
            "isDefault": true
        }
    ]
}

/weeklabelmaps/{key}   (since MyTimetable 2.7)

Method: GET

Description: Retrieve the specified weeklabel map. This provides the key, a boolean which indicates if this is the default weeklabel map for the requested user and the actiual map with custom labels for the weeks.

...

Code Block
languagejs
{
    "key": "SYLLABUS",
    "isDefault": true,
    "weeklabels": [
        {
            "year": 2014,
            "week": 4,
            "description": "wk 4"
        },
        {
            "year": 2014,
            "week": 5,
            "description": "wk 5"
        }
    ]
}

/databases    (deprecated since MyTimetable 3.1, replaced by: /databasedetails)

Method: GET

Description: Query the available datasources, see 3114172430API Documentation for more information. For MyTimetable 3.1+, please use the /databasedetails call, which also provides the labels of the databases.

...

Code Block
languagenone
{
    "database": [
        "2011"
    ]
}

/databasedetails   (since MyTimetable 3.1)

Method: GET

Description: Query the available datasources, see 3114172430API Documentation for more information. The key (to be used in the query string of other calls) and the label are returned.

...

Code Block
languagenone
{
    "databases": [
        {
            "key": "2015",
            "label": "2015/2016"
        },
        {
            "key": "2016",
            "label": "2016/2017"
        },
        {
            "key": "TimetableDB",
            "label": "Custom"
        }
    ]
}

/eventtypegroups   (since MyTimetable 3.0)

Method: GET

Description: Query the event type groups and event filtering settings.

...

Code Block
languagenone
$base_url/api/v0/eventtypegroups

Request Content-Type

application/x-www-form-urlencoded

Example request body

Code Block
languagenone
eventTypeGroups%5BExcursie%5D%5BisFiltered%5D=true&eventTypeGroups%5BHoorcollege%5D%5BisFiltered%5D=false&eventTypeGroups%5BOther%5D%5BisFiltered%5D=false

...

204 (No content), 403 (Forbidden) if filtering is disabled.

/terms   (since MyTimetable 3.4)

Method: GET

Description: Query the available terms. Returns a list of terms, each containing of a unique id, a key (may be null), a name and a list of date ranges.

...

Code Block
languagenone
{
    "terms": [
        {
            "dateRanges": [
                {
                    "endDate": 1513983600000,
                    "startDate": 1504476000000
                },
                {
                    "endDate": 1535925600000,
                    "startDate": 1514847600000
                }
            ],
            "id": "2017!492E26C5A6F3BDE74C11240C046C2FB1",
            "key": null,
            "name": "[2017/2018] All year"
        },
        {
            "dateRanges": [
                {
                    "endDate": 1535925600000,
                    "startDate": 1504476000000
                }
            ],
            "id": "TermTime!13",
            "key": "All",
            "name": "[Term Time] All year"
        }
    ]
}


/user/messages   (since MyTimetable 4.0)

Note: this API endpoint always returns application/json as Content Type. XML is not supported.

Method: GET

Description: Query the active messages for the current user (as identified by the OAuth token or elevated API token). Requires scope messages_read.

...

Response code

200 (OK)

/messages   (since MyTimetable 4.0)

Note: this API endpoint always returns application/json as Content Type. XML is not supported.

Method: GET

Description: Retrieves messages. Requires API token scope ROLE_API_MESSAGES.

...

NameDescriptionDefault value
title (required)
Title of the message.-
body (required)Body of the message. Markdown formatting can be used.-
importantSets if a message should be considered important.false
publicationDatePublication date. The message will be shown as of this date. See below for the date format.null
expirationDateExpiration date. The message will be shown until this message, or forever if set to null. See below for the date format.null
targetRolesUser roles to target this message to. If not set, all users can view the message.[ ]

...

Request Content-Type header

application/x-www-form-urlencoded

Example request body

Code Block
languagenone
title=This%20is%20the%20title%20of%20a%20non-expiring%20message%20targeted%20to%20students%20marked%20as%20important.&body=%23%20This%20is%20a%20header%20formatted%20with%20Markdown%0AThis%20is%20some%20content.&important=true&publicationDate=2019-01-02&expirationDate=&targetRoles=ROLE_STAFF&targetRoles=ROLE_STUDENT

...

201 (Created) if the message is created, 400 (Bad Request) if input validation fails

/messages/{id}   (since MyTimetable 4.0)

Note: this API endpoint always returns application/json as Content Type. XML is not supported.

Method: GET

Description: Retrieves the message with the given ID. Requires API token scope ROLE_API_MESSAGES.

...

NameDescriptionDefault value
title
Title of the message.-
bodyBody of the message. Markdown formatting can be used.-
importantSets if a message should be considered important.false
publicationDatePublication date. The message will be shown as of this date. See below for the date format.null
expirationDateExpiration date. The message will be shown until this message, or forever if set to null. See below for the date format.null
targetRolesUser roles to target this message to. If not set, all users can view the message.[ ]

...

Request Content-Type header

application/x-www-form-urlencoded

Example request body

Code Block
languagenone
title=This%20is%20the%20edited%20title%20of%20a%20non-expiring%20message%20targeted%20to%20students%20marked%20as%20important.&body=%23%20This%20is%20an%20edited%20header%20formatted%20with%20Markdown%0AThis%20is%20some%20content.&important=false&publicationDate=2019-03-11&expirationDate=&targetRoles=ROLE_STAFF&targetRoles=ROLE_STUDENT

...