API Documentation

Introduction

The MyTimeTable API allows you to retrieve timetables and alter user's MyTimetable profiles. Most of the data in MyTimetable can be accessed using the API, and the possibilities are expanded continuously. The API is based on REST principles, and is currently on version 0. Requests can be done using the various available HTTP verbs (GET, POST, PUT and DELETE).

The API documentation uses the variable $base_url to refer to the base URL of MyTimetable. This URL depends on the customer and can be found on the Customer-specific API information page.

Not all MyTimetable sites have enabled API access. Some customers choose to enable API access only for certain trusted applications. Please contact us if you have questions about the API or if you would like to receive an access token for a certain API.

Data structure

A student's timetable is made up of one or more individual timetables. These timetables are all of a certain type. The exact meaning of a type depends on the customer (see Customer-specific API information), but the table below gives an idea of the options:

Type	Meaning
student	Personal timetable of a student (when available, most institutions do not have personal timetables available in their timetabling application).
staff	Personal timetable of a staff member.
module	Timetable for a module or course.
pos	Timetable for a programme of study (group of modules).
posss	Timetable for a programme of study (group of studentsets and associated modules). This is a different implementation that the pos type, and the exact type available depends on the institution.
studentset	Timetable for a certain group of students (usually the timetable for a class or study group).
studentsetgroup	Timetable for a group of studentsets (most customers use either studentset or studentsetgroup to the outside world).
modulepos	Timetable for a certain module, but limited to the studentsets of a certain study programme. This is used if a module is shared between study programmes, but contains activities that are specific to a certain study programme.
user	Personal timetable for a user (can be both a student or a staff member).
location	Timetable for a certain (class)room.
zone	Timetable for a building or other grouping of rooms.

The API gives the option to either query a user's complete personal timetable, based on his or her MyTimetable subscriptions, or a single timetable which is not based on a user's profile. The first option always requires a certain form of authentication, whereas the second option may be available without any authentication or only requires an API token. An example workflow for both scenarios:

Personal timetable
- Request access to the user's personal timetable by using OAuth, or use impersonation using an API token (if available).
- Retrieve a list of a user's subscriptions using the /subscriptions call.
- Retrieve the timetable of a user using the /timetable call.
- Add or remove subscriptions to a user's profile by using the /subscriptions calls. To retrieve a list of timetables that can be added, one can use the /timetables call.
Single timetable
- Retrieve a list of timetables for a certain type by using the /timetables call.
- The list of the previous call can be filtered using several filter options. The values for these filters can be retrieved using the /timetablefilters call.
- After choosing the right timetable, the contents of the timetable can be retrieved using the /timetables/<key> call.

Multiple databases

Output format

The resources support both JSON and XML. By default, the returned format depends on the HTTP Accept header. Use application/json for JSON and application/xml for XML. It is also possible to specify the output format in the URL, by appending .json or .xml to the resource name, before the query string.

Authentication and authorisation

WADL

A machine readable XML based description of the API in WADL format can be viewed using the following url:

$base_url/api/v0?_wadl

Resources

/timetables

Description: Query all timetables with a specified type.

Type: GET

Parameters

type	the type of the timetables, e.g. 'module'
limit	the maximum amount of records returned
offset	starting position of the records returned (e.g. offset=5 skips the first 5 records)
departmentFilter	filter on a specific department
posFilter	filter on a specific pos
zoneFilter	filter on a specific zone

Request URL

$base_url/api/v0/timetables?type=module

Response Body

[
    {
    	"description": "VMT for Informatics", 
    	"value": "2011!module!49CBD432F01E8C5057B344E02604A710"
    }
]

/timetables/{key}

Description: Query all timetables corresponding with a specific timetable.

Type: GET

Parameters

key	the key corresponding with the specific timetable
startDate	the start date for the timetable
endDate	the end date for the timetable
limit	the maximum amount of records returned (default = 25)

Request URL

$base_url/api/v0/timetables/2011!module!49CBD432F01E8C5057B344E02604A710

Response Body

[
   {
        "activityDescription": "VMT for Informatics", 
        "activityTypeDescription": "Lecture", 
        "activityTypeName": "Class", 
        "endDate": 1341930600000, 
        "locations": [
            {
                "capacity": 18, 
                "id": "D2D0C6A8E334B242289FBAA7F69759C3", 
                "key": "#SPLUS9759C3", 
                "name": "B3.022"
            }
        ], 
        "moduleCode": "#SPLUS04A710", 
        "notes": null, 
        "staffMembers": [
            "Mr. Moore (Moo)"
        ], 
        "startDate": 1341919800000, 
        "studentSets": [
            "BI group  1A", 
            "BI group  1B"
        ]
    }
]

/timetable

Description: Query all timetables within a specific timerange.

Type: GET

Parameters

startDate	the start date for the timetable
endDate	the end date for the timetable
limit	the maximum amount of records returned
type	the type of the timetables, e.g. 'module'

Request URL

$base_url/api/v0/timetable?startDate=2012/07/10&endDate=2012/07/10

Response Body

{
        "activityDescription": "System biology", 
        "activityTypeDescription": "Lecture", 
        "activityTypeName": "Class", 
        "endDate": 1341916200000, 
        "locations": [
            {
                "capacity": 24, 
                "id": "D2D0C6A8E334B242289FBAA7F69759BB", 
                "key": "#SPLUS9759BB", 
                "name": "G3.104"
            }, 
            {
                "capacity": 24, 
                "id": "D2D0C6A8E334B242289FBAA7F69759BC", 
                "key": "#SPLUS9759BC", 
                "name": "G3.110"
            }
        ], 
        "moduleCode": "#SPLUS969C58", 
        "notes": null, 
        "staffMembers": [
            "Mr. Martinez (Maz)", 
            "Ms. Adams (Ada)"
        ], 
        "startDate": 1341909000000, 
        "studentSets": [
            "BI group  3A"
        ]
}

/timetabletypes

Description: Query all possible timetable types.

Type: GET

Parameters: none

Request URL

$base_url/api/v0/timetabletypes

Response Body

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

/timetablefilters

Description: Query all filters available for a specific timetable type.

Type: GET

Parameters

type	the type of the timetable
departmentFilter	a specific filter

Request URL

$base_url/api/v0/timetablefilters?type=pos

Response Body

{
    "filterattribute": [
        {
            "option": [
                {
                    "name": " Faculty of Informatics", 
                    "value": "646ADCA666D4A88402CA46C26A73803C"
                }, 
                {
                    "name": " Faculty of Law", 
                    "value": "646ADCA666D4A88402CA46C26A738046"
                }
            ], 
            "type": "department"
        }
    ]
}

/databases

Description: Query the available databases.

Type: GET

Parameters: none

Request URL

$base_url/api/v0/databases

Response Body

{
    "database": [
        "2011"
    ]
}

/weeklabels

Description: Query the weeklabels.

Type: GET

Parameters: none

Request URL

$base_url/api/v0/weeklabels

Response Body

{
     "value": "23", 
     "week": 11223
}

/subscriptions

Type: DELETE

Description: Delete all subscriptions

Parameters: none

Request URL

$base_url/api/v0/subscriptions

/subscriptions/{key}

Type: POST

Description: Add a new subscription

Parameters

key

the key of the subscription you wish to add

Request URL

$base_url/api/v0/subscriptions/2011!pos!0F2C927DF37F3A2BEF1F1713768E4EE6

Response code: 204 (No content)

Type: DELETE

Description: Delete a subscription.

Parameters

key

the key of the subscription you wish to delete

Request URL

$base_url/api/v0/subscriptions/2011!pos!0F2C927DF37F3A2BEF1F1713768E4EE6

Response code: 204 (No content)

Type: PUT

Description: Edit a subscription. Use boolean values to trigger the subscription on or off.

Parameters

key	the key of the subscription you wish to edit
state	boolean value indicating the state of the subscription

Request URL

$base_url/api/v0/subscriptions/2011!pos!0F2C927DF37F3A2BEF1F1713768E4EE6?state=false

Response Code: 204 (No content)

/subscriptions/{parent}/{key}

Type: PUT

Description: Edit a subscription nested under a parent. Use boolean values to trigger the subscription on or off.

Parameters

key	the key of the subscription you wish to edit
parent	the key of the parent of the subscription
state	boolean value indicating the state of the subscription

Request URL

$base_url/api/v0/subscriptions/2011!location!D2D0C6A8E334B242289FBAA7F69759C3/2011!module!49CBD432F01E8C5057B344E02604A773?state=false

Response Code: 204 (No content)