Page Comparison

Introduction

...

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

...

New fields may be added to objects without incrementing the version number. See API Documentation 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.

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:

Code Block
$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 API Documentation 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

/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

Example request URL

Code Block

language	none

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

Example response body

Code Block

language	none

[
    {
    	"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)

Example request URL

Code Block

language	none

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

Example response body

...

language	none

...

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 should be specified in the following format (which is totally inconsistent with the rest of our API, we will fix this in the next version): YYYY/MM/DD HH:MM. The time part is optional and will be regarded as 0:00 if not specified.

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:

Code Block
$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 API Documentation 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

Description: Query all possible timetable types, these types serve as input for the /timetables, /timetable and /timetablefilters calls. See API Documentation for a discussion on the meaning of the types.

Method: GET

Parameters: none

Request URL

Code Block

language	none

$base_url/api/v0/timetabletypes

Example response body

Code Block

language	none

{
    "timetableType": [
        "location", 
        "zone", 
        "module", 
        "student", 
        "staff", 
        "pos", 
        "posss", 
        "studentset", 
        "studentsetgroup", 
        "modulegroup", 
        "activityTypeDescriptionuser":
"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'

]
}

/timetables

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

Method: GET

Parameters

Name	Description	Default value
`type`(required)	the type of the timetables, e.g. 'module'	-
`limit`	the maximum amount of records returned	0
`offset`	starting position of the records returned (e.g. offset=5 skips the first 5 records)	0
`departmentFilter`	filter on a specific department	-
`departmentGroupFilter`	filter on a specific department group	-
`posFilter`	filter on a specific pos	-
`zoneFilter`	filter on a specific zone	-

Example request URL

Code Block

language	none

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

Example response body

Code Block

language	none

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

/timetables/{key}

Description: Query the schedule for the specified timetable identifier.

Method: GET

Parameters

Name	Description	Default value
`key` (required)	the key corresponding with the specific timetable, as retrieved using the /timetables call	-
`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 URL

Code Block

language	none

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

...

timetables/2011!module!49CBD432F01E8C5057B344E02604A710

Example response body

Code Block

language	none

[
   {
        "activityDescription": "SystemVMT for biologyInformatics", 
        "activityTypeDescription": "Lecture", 
        "activityTypeName": "Class", 
        "endDate": 13419162000001341930600000, 
        "locations": [
            {
                "capacity": 2418, 
                "id": "D2D0C6A8E334B242289FBAA7F69759BBD2D0C6A8E334B242289FBAA7F69759C3", 
                "key": "#SPLUS9759BB#SPLUS9759C3", 
                "name": "G3B3.104022"
            },
        ], 
   {       "moduleCode": "#SPLUS04A710", 
        "capacitynotes": 24, 
      null, 
        "idstaffMembers": "D2D0C6A8E334B242289FBAA7F69759BC",[
            "Mr.     "key": "#SPLUS9759BC",Moore (Moo)"
        ], 
        "namestartDate": "G3.110"1341919800000, 
        "studentSets": [
 }         ],  "BI group    1A", 
 "moduleCode": "#SPLUS969C58",          "notes": null,BI group  1B"
       "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

Code Block

language	none

$base_url/api/v0/timetabletypes}
]

/timetable

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

Method: GET

Parameters

Name	Description	Default 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`	the type of the timetables, e.g. 'module'	-

Example request URL

Code Block

language	none

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

Example response body

Code Block

language	none

{
        "timetableTypeactivityDescription": [
        "location","System biology", 
        "activityTypeDescription": "zoneLecture", 
        "moduleactivityTypeName": "Class", 
        "studentendDate": 1341916200000, 
        "stafflocations",: [
         "pos",   {
      "posss",          "studentsetcapacity": 24, 
        "studentsetgroup",         "id": "modulegroupD2D0C6A8E334B242289FBAA7F69759BB", 
         "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

Example request URL

Code Block

language	none

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

Example response Body

Code Block

language	none

{
    "filterattribute": [
     "key": "#SPLUS9759BB", 
                "name": "G3.104"
            }, 
   {         {
   "option": [            "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

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

Method: GET

Parameters

type	the type of the timetable
departmentFilter	a specific filter

Example request URL

Code Block

language	none

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

Example response Body

Code Block

language	none

{
         "namefilterattribute": "[
Faculty of Informatics",         {
            "valueoption": "646ADCA666D4A88402CA46C26A73803C"
 [
              },                  {
                    "name": " Faculty of LawInformatics", 
                    "value": "646ADCA666D4A88402CA46C26A738046646ADCA666D4A88402CA46C26A73803C"
                }, 
           ],          {
   "type": "department"           }     ]
}

/databases

Description: Query the available databases.

Type: GET

Parameters: none

Request URL

Code Block

language	none

$base_url/api/v0/databases

Example response body

Code Block

language	none

{
    "database": [ "name": " Faculty of Law", 
        "2011"     ] }

/weeklabels

Description: Query the weeklabels.

Type: GET

Parameters: none

Request URL

Code Block

language	none

$base_url/api/v0/weeklabels

Example response body

Code Block

language	none

{      "value": "23",646ADCA666D4A88402CA46C26A738046"
                }
            ], 
            "weektype": 11223 "department"
        }
    ]
}

/subscriptions

TypeMethod: DELETE

Description: Delete all subscriptions

...

Code Block

language	none

$base_url/api/v0/subscriptions

/subscriptions/{key}

...

key}

Method: POST

Description: Add a new subscription

Parameters

key

the key of the timetable you wish to add

Example request URL

Code Block

language	none

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

Response code: 204 (No content)

Method: DELETE

Description: Add Delete a new subscription.

Parameters

key

the key of the subscription you wish to adddelete

Example request URL URL

Code Block

language	none

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

Response code: 204 (No content)

TypeMethod: DELETEPUT

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

Parameters

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

Example request URL

Code Block

language	none

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

Response codeCode: 204 (No content)Type

/subscriptions/{parent}/{key}

Method: PUT

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

...

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

...

Code Block

language	none

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

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

...

location!D2D0C6A8E334B242289FBAA7F69759C3/2011!module!49CBD432F01E8C5057B344E02604A773

Response Code: 204 (No content)

/weeklabels

Description: Query the weeklabels.

Method: GET

Parameters: none

Request URL

Code Block

language	none

$base_url/api/v0/weeklabels

Example response body

Code Block

language	none

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

/databases

Description: Query the available databases.

Method: GET

Parameters: none

Request URL

Code Block

language	none

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

...

databases

Example response body

Code Block

language	none

{
    "database": [
        "2011"
    ]
}

Version	Old Version 24	New Version 25
Changes made by	Former user	Former user
Saved on	Dec 17, 2012	Dec 17, 2012

Versions Compared

Key

Table of Contents

Introduction

Table of Contents

Introduction

Input and output format

Authentication and authorisation

WADL

Version numbering

Multiple databases

Resources

/timetables

/timetables/{key}

Authentication and authorisation

WADL

Version numbering

Multiple databases

Resources

/timetabletypes

/timetable

/timetables

/timetables/{key}

/timetabletypes

/timetable

/timetablefilters

/timetablefilters

/databases

/weeklabels

/subscriptions

/subscriptions/{key}

key}

/subscriptions/{parent}/{key}

/subscriptions/{parent}/{key}

/weeklabels

/databases