Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 37 Next »

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:

TypeMeaning
studentPersonal timetable of a student (when available, most institutions do not have personal timetables available in their timetabling application).
staffPersonal timetable of a staff member.
moduleTimetable for a module or course.
posTimetable for a programme of study (group of modules).
posssTimetable 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.
studentsetTimetable for a certain group of students (usually the timetable for a class or study group).
studentsetgroupTimetable for a group of student sets (most customers use either studentset or studentsetgroup to the outside world).
moduleposTimetable 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.
userPersonal timetable for a user (can be both a student or a staff member).
locationTimetable for a certain (class)room.
zoneTimetable 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.

A timetable always consists of a list of Event objects and is sorted by event start and end date. The events contain the following values:

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 and capacity).
staffMembersList of staff members associated with the event.
notesSome notes or additional information about the event, not all customers use this field.

New fields may be added to objects without incrementing the version number. See Version numbering for details.

Input and output format

The resources support both JSON and XML output. 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. Dates and times are returned in ISO 8601 format (yyyy-MM-ddTHH:mm:ss±HH:mm) when retrieving results in XML, and in Unix timestamp format when retrieving JSON. 

Output can be available in multiple languages. Use the Accept-Language HTTP header to specify the locale, for example NL-nl. When the specified locale is not available, the default locale will be used.

Input can be provided in the form of HTTP GET URL parameters 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;
  • 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

Depending on the wishes of the institution, the MyTimetable API can require several forms of authentication and authorisation.

First of all, it can be necessary for the client application to provide some form of authentication. This makes sure only authorised applications can access the API data. This authorisation is usually done using an API token. Next to the client authentication, sometimes the client application wants to access the personal data of a user. The user can either provide authorise the application to access this data, using OAuth, or the client can use a special API token with elevation privileges. Some MyTimetable environment only allow API access for requests that can be linked to a real user. In these cases an OAuth token is always necessary.

In the requests below we have not included the authorisation information (like the access_token query parameter or the apiToken header). The page with Customer-specific API information lists the requirements of the different MyTimetable environments available.

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

Version numbering

The API uses a version numbering scheme and the base URL of the API is: $base_url/api/v$version. The current API version is version 0. Non-breaking changes (like the addition of extra information or methods) will be done without incrementing the version number. On breaking changes the version number will be increased. Multiple API versions may exist at the same time. Eveoh will try to support older API versions when technically and economically feasible, but users are encouraged to always use the latest API version.

Multiple databases

During a year rollover, multiple databases with timetabling data may be available. By specifying a GET parameter d, it is possible to select a certain database for the request. The list of possible databases can be retrieved with the /databases call. If no database is specified, the default database will be used, which is usually the most sensible option. In the future, the API will remove the need to specify a database with a request and will transparently query multiple databases when necessary.

Resources

/timetabletypes

MethodGET

Description: Query all possible timetable types, these types serve as input for the /timetables/timetable and /timetablefilters calls. See Data structure for a discussion on the meaning of the types. Currently this call returns all possible types of the configured backend, the customer may not use all these types. See Customer-specific API information to find out what types the customer uses.

Parameters: none

Request URL

$base_url/api/v0/timetabletypes

Example response body

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

/timetables

Method: GET

Description: Query a list of timetables for a specified type. The filters that can be specified can be retrieved using the /timetablefilters call. Returns a list of descriptions and identifiers. The identifiers can be used in subsequent calls to /timetables/{key} and /subscriptions/{key}.

Parameters

NameDescriptionDefault value
type (required)The type of the timetables, e.g. 'module'.-
limitThe maximum amount of records returned.0
offsetStarting position of the records returned (e.g. offset=5 skips the first 5 records).0
departmentFilter
Filter results on a specific department.-
departmentGroupFilter
Filter results on a specific department group.-
posFilter
Filter results on a specific pos.-
zoneFilter
Filter results on a specific zone.-

Example request URL

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

Example response body

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

/timetables/{key}

Method: GET

Description: Query the schedule for the specified timetable identifier.

Parameters

NameDescriptionDefault value
key (required)
The key corresponding with the specific timetable, as retrieved using the /timetables call.-
fetchByUse 'hostKey' to retrieve the events by it's timetable host key instead of timetable key. (MyTimetable v2.3 and higher)-
startDate
The start date to retrieve events from, or 'today' for the current date at 0:00, or 'tomorrow' for tomorrow at 0:00, or none for the beginning of times.-
endDate
The end date to retrieve events till, or 'today' for the current date at 0:00, or 'tomorrow' for tomorrow at 0:00, or none for the end of times.-
limit
The maximum amount of records returned, 0 for no limit.0

Example request URLs

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

Example 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

Method: GET

Description: Query the personal timetable for the current user (as identified by the OAuth token or elevated API token).

Parameters

NameDescriptionDefault value
startDate
The start date to retrieve events from, or 'today' for the current date at 0:00, or 'tomorrow' for tomorrow at 0:00, or none for the beginning of times.-
endDate
The end date to retrieve events till, or 'today' for the current date at 0:00, or 'tomorrow' for tomorrow at 0:00, or none for the end of times.-
limit
The maximum amount of records returned, 0 for no limit.0
type
Specifies the type of the subscriptions to include when returning the timetable, can be specified multiple times, useful to exclude zone and location subscriptions when requesting the timetable. If not specified all subscriptions will be included in the result.-

Example request URL

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

Example 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"
        ]
	}
]

/timetablefilters

MethodGET

Description: Query all filters available for a specific timetable type. Using the results it is possible to filter the output of this call and of the /timetables call. Returns a list of possible filtertypes. For each type a list of possible filter descriptions and identifiers is provided.

Parameters

NameDescriptionDefault value
type (required)
The type of the timetables to retrieve the filters for.-
departmentFilter
Filter results on a specific department.-
departmentGroupFilter
Filter results on a specific department group.-
zoneFilter
Filter results on a specific zone.-

Example request URL

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

Example response Body

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

/subscriptions

MethodGET

Description: Retrieves all subscriptions for the current user (as identified by the OAuth token or elevated API token).

Parameters:

NameDescriptionDefault value
type
Specifies the type of the subscriptions to include, can be specified multiple times, useful to exclude zone and location subscriptions when requesting a personal list of subscriptions. If not specified all subscriptions will be included in the result.-

Request URL

$base_url/api/v0/subscriptions

Example response Body

[ 
	{
		"key":"2011!module!49CBD432F01E8C5057B344E02604A711",
		"description":"Basic chemical reactions",
		"childSubscriptions":[],
		"enabled":false,
		"removable":true
	}
]


MethodDELETE

Description: Delete all subscriptions

Parameters: none

Request URL

$base_url/api/v0/subscriptions

Response code: 204 (No content)

/subscriptions/{key}

MethodPOST

Description: Add a new subscription

Parameters

NameDescriptionDefault value
key (required)
The key of the timetable you wish to add.-

Example request URL 

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

Response code: 204 (No content)

 

MethodDELETE

Description: Delete a subscription.

Parameters

NameDescriptionDefault value
key (required)
The key of the subscription you wish to delete.-

Example request URL

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

Response code: 204 (No content)


MethodPUT

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

Parameters

NameDescriptionDefault value
key (required)
The key of the subscription you wish to edit.-
state
Boolean value indicating the state of the subscription.false

Example request URL

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

Response Code: 204 (No content)

/subscriptions/{parent}/{key}

MethodPUT

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

Parameters

NameDescriptionDefault value
key (required)The key of the subscription you wish to edit.-
parent (required)
The key of the parent of the subscription.-
state
Boolean value indicating the state of the subscription.false

Example request URL

$base_url/api/v0/subscriptions/2011!location!D2D0C6A8E334B242289FBAA7F69759C3/2011!module!49CBD432F01E8C5057B344E02604A773

Response Code: 204 (No content)

/user

Description: Query information on the current user. Currently this returns the username and the iCalendar feed URL for the current user.

MethodGET

Parameters: none

Request URL

$base_url/api/v0/user

Example response body

{
     "feedUrl": "http://myuniversity/ical?eu=FKW92Fawier&t=556cf8a1-704a-4997-bc4d-5acf395eccaf",
     "username": "testuser"
}

/weeklabels

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).

MethodGET

Parameters: none

Request URL

$base_url/api/v0/weeklabels

Example response body

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

/databases

Description: Query the available databases, see Multiple databases for more information.

MethodGET

Parameters: none

Request URL

$base_url/api/v0/databases

Example response body

{
    "database": [
        "2011"
    ]
}
  • No labels