docs/Sirius.raml
#%RAML 0.8
title: CTU Sirius API
version: v1
baseUri: https://sirius.fit.cvut.cz/api/{version}
securitySchemes:
- oauth2:
type: OAuth 2.0
description: >
Sirius uses OAuth 2.0 authorization server of FIT CTU.
See https://rozvoj.fit.cvut.cz/Main/oauth2 for more information.
describedBy:
headers:
Authorization:
description: >
Used to send a valid OAuth 2 access token. Do not use with the `access_token` query
string parameter.
example: Bearer 07a855e0-6920-11e4-a40a-0002a5d5c51b
queryParameters:
access_token:
description: >
Used to send a valid OAuth 2 access token. Do not use together with the
`Authorization` header. It’s recommended to use the `Authorization` header
instead of the query parameter.
example: 07a855e0-6920-11e4-a40a-0002a5d5c51b
responses:
401:
description: >
Bad or expired token. This can happen if the user or OAAS revoked or expired
an access token. To fix, you should request a new token.
403:
description: >
Bad OAuth request (wrong client secret, scopes, expired token...).
settings:
authorizationUri: https://auth.fit.cvut.cz/oauth/authorize
accessTokenUri: https://auth.fit.cvut.cz/oauth/token
authorizationGrants: [ client_credentials, authorization_code ]
scopes:
- cvut:sirius:all:read
- cvut:sirius:personal:read
- cvut:sirius:limited-by-idm:read
traits:
- paged:
usage: Retreive further pages in collection
description: Use `offset` and `limit` to paginate the records.
queryParameters:
limit:
description: The number of entries in collection to return
type: number
default: 10
maximum: 100
offset:
description: Offset of the first entry in collection
type: number
default: 0
- dateScoped:
queryParameters:
from:
description: Return events from this date
type: date
to:
description: Return events up to this date
type: date
- deletable:
queryParameters:
deleted:
description: Return even events that have been deleted.
type: boolean
default: false
- filterable:
queryParameters:
event_type:
description: Filter by event's type
type: string
enum: [ assessment, course_event, exam, laboratory, lecture, teacher_timetable_slot, tutorial ]
- includable:
description: >
Includes the specified linked resources into the response (similar to compound documents
in the JSON API format).
queryParameters:
include:
description: A comma-separated list of the link names to include.
type: string
example: courses,teachers,schedule_exceptions
resourceTypes:
- events-collection:
get:
is: [ dateScoped, deletable, filterable, includable, paged ]
securedBy: [ oauth2 ]
queryParameters:
with_original_date:
description: >
When the date of event has been changed by a schedule exception, original date is not
considered for date filtering (by from/to parameters). With this parameter Sirius will
include events’ original date in a date filter.
type: boolean
default: false
responses:
200:
body:
application/json:
example: |
{
"meta": {
"count": 2,
"offset": 0,
"limit": 20
},
"events": [
{
"id": 42,
"name": null,
"sequence_number": 12,
"starts_at": "2014-04-23T09:15:00.000+02:00",
"ends_at": "2014-04-23T10:45:00.000+02:00",
"deleted" : false,
"capacity": 24,
"occupied": 20,
"event_type": "tutorial",
"parallel": "106",
"original_data": {
"starts_at": "2014-04-23T09:00:00.000+02:00",
"ends_at": "2014-04-23T10:30:00.000+02:00",
"room_id": "T9:111"
},
"links": {
"room": "T9:350",
"course": "MI-RUB",
"teachers": [
"skocdopet"
],
"students": [
"szolatib",
"vomackar"
],
"applied_exceptions": [ 10, 15 ]
}
},
{
"id": 43,
"name": null,
"sequence_number": 12,
"starts_at": "2014-04-24T09:15:00.000+02:00",
"ends_at": "2014-04-24T10:45:00.000+02:00",
"deleted" : false,
"capacity": 196,
"occupied": 190,
"event_type": "lecture",
"parallel": "1",
"original_data": {},
"links": {
"room": "T9:155",
"course": "MI-W20",
"teachers": [
"kuchajar",
"vitvatom"
],
"students": [
"jirutjak"
]
}
}
]
}
text/calendar:
example: |
BEGIN:VCALENDAR
VERSION:2.0
CALSCALE:GREGORIAN
BEGIN:VEVENT
DTSTAMP:20140702T140133Z
UID:https://sirius.fit.cvut.cz/events/123
DTSTART:20140312T101500
DTEND:20140312T114500
CLASS:PUBLIC
CREATED:20140410T182546
LAST-MODIFIED:20140410T182546
LOCATION:T9:130
SUMMARY:MI-PSL 2. cvičení
END:VEVENT
BEGIN:VEVENT
DTSTAMP:20140702T140133Z
UID:https://sirius.fit.cvut.cz/events/125
DTSTART:20140312T101500
DTEND:20140312T114500
CLASS:PUBLIC
CREATED:20140410T182546
LAST-MODIFIED:20140410T182546
LOCATION:T9:130
SUMMARY:MI-PSL 2. cvičení
END:VEVENT
END:VCALENDAR
404:
description: There are no events within the current scope
- event:
get:
securedBy: [ oauth2 ]
responses:
200:
body:
application/json:
example: |
{
"events": {
"id": 42,
"name": null,
"sequence_number": 12,
"starts_at": "2014-04-23T07:30:00.000+02:00",
"ends_at": "2014-04-23T11:00:00.000+02:00",
"deleted" : false,
"capacity": 24,
"occupied": 18,
"event_type": "tutorial",
"parallel": "106",
"original_data": {
"starts_at": "2014-04-23T09:00:00.000+02:00",
"ends_at": "2014-04-23T10:30:00.000+02:00",
"room_id": "T9:111"
},
"links": {
"room": "T9:350",
"course": "MI-RUB",
"teachers": [
"skocdopet"
],
"students": [
"szolatib",
"vomackar"
],
"applied_exceptions": [ 10, 15 ]
}
}
}
text/calendar:
example: |
BEGIN:VCALENDAR
VERSION:2.0
CALSCALE:GREGORIAN
BEGIN:VEVENT
DTSTAMP:20140702T140133Z
UID:https://sirius.fit.cvut.cz/events/123
DTSTART:20140312T101500
DTEND:20140312T114500
CLASS:PUBLIC
CREATED:20140410T182546
LAST-MODIFIED:20140410T182546
LOCATION:T9:130
SUMMARY:MI-PSL 2. cvičení
END:VEVENT
END:VCALENDAR
/events:
type: events-collection
get:
description: Get a collection of events without any scope.
/{eventId}:
type: event
get:
description: Get event with the specified ID.
/people/{username}:
securedBy: [ oauth2 ]
uriParameters:
username:
description: person's unique username
required: true
pattern: "[a-z0-9]{3,8}"
example: flynnkev
get:
description: |
Get person's full name and _local_ access token. This token allows access to her personal
calendar only and it's intended for iCalendar.
responses:
200:
body:
application/json:
example: |
{
"people": {
"id": "elisruby",
"full_name": "Ing. Elisia Ruby",
"access_token": "72816e82-f5b2-4909-b7c7-770ad017e645"
}
}
/events:
type: events-collection
get:
description: Get a calendar for the person.
/teachers/{username}/events:
type: events-collection
uriParameters:
username:
description: Person's unique username.
required: true
pattern: "[a-z0-9]{3,8}"
example: flynnkev
get:
description: >
Get a teacher's calendar for the specified person. This is a subset of the person's calendar
with only events which the person teaches (classes), examines (exams) or organizes
(one-off events).
/rooms/{kosId}/events:
type: events-collection
uriParameters:
kosId:
description: >
Common room identification used by KOS, for details see
[the documentation](https://rozvoj.fit.cvut.cz/Main/znaceni-mistnosti#HKOSEDzna10DenED-102).
required: true
pattern: "[A-Z0-9]{2}:([A-Z0-9]+-)?[a-z0-9]+"
example: "TH:A-1333"
get:
description: Get a calendar for the room.
/courses/{courseCode}/events:
type: events-collection
uriParameters:
courseCode:
description: |
Course code, faculty specific.
required: true
example: BI-PA1
get:
description: Get a calendar for the course.
/faculties/{facultyId}:
uriParameters:
facultyId:
description: Faculty code (5 digits).
required: true
example: 18000
/schedule:
/days:
is: [ dateScoped ]
get:
description: Get a collection of semester-related parameters for the specified days.
responses:
200:
body:
application/json:
/{date}:
uriParameters:
date:
description: The date to resolve, or string `current` for the current day.
required: true
example: 2016-01-06
get:
description: Get semester-related parameters for the specified day.
responses:
200:
body:
application/json:
example: |
{
"semester_days": {
"date": "2016-01-06",
"cwday": 3,
"period_type": "teaching",
"teaching_week": 13,
"week_parity": "even",
"links": {
"semester": "18000-B151",
"period": 8
}
}
}
/weeks:
is: [ dateScoped ]
get:
description: Get a collection of semester-related attributes of the specified weeks.
responses:
200:
body:
application/json:
/{year_cweek}:
uriParameters:
year_cweek:
description: >
An ISO 8601 week-based year and week number of the week to resolve, or string
`current` for the current week.
required: true
example: 2015-52
get:
description: Get semester-related attributes of the specified week.
responses:
200:
body:
application/json:
example: |
{
"semester_weeks": {
"starts_at": "2015-12-21",
"ends_at": "2015-12-27",
"cweek": 52,
"period_types": [ "teaching", "holiday" ],
"teaching_week": 12,
"week_parity": "even",
"links": {
"semester": "18000-B151",
"periods": [ 5, 6, 7 ]
}
}
}
/semesters:
is: [ paged ]
get:
description: Get a collection of semesters for the faculty.
responses:
200:
body:
application/json:
example: |
{
"semesters": [
{
"id": "18000-B142",
"semester": "B142",
"faculty": 18000,
"starts_at": "2015-02-16",
"ends_at": "2015-09-21",
"exams_start_at": "2015-05-18",
"exams_end_at": "2015-06-27",
"teaching_ends_at": "2015-05-16",
"first_week_parity": "even",
"hour_duration": 45,
"hour_starts": [
"07:30", "08:15", "09:15", "10:00", "11:00", "11:45",
"12:45", "13:30", "14:30", "15:15", "16:15", "17:00",
"18:00", "18:45", "19:45"
]
}
],
"meta": {
"count": 4,
"offset": 0,
"limit": 1
}
}
/{code}:
uriParameters:
code:
description: A semester code.
pattern: "[AB][0-9]{2}[12]"
example: 18000-B142
required: true
get:
description: Get a semester with the specified KOS code for the faculty.
responses:
200:
body:
application/json:
example: |
{
"semesters": {
"id": "18000-B151",
"semester": "B151",
"faculty": 18000,
"starts_at": "2015-10-05",
"ends_at": "2016-02-22",
"exams_start_at": "2016-01-11",
"exams_end_at": "2016-02-21",
"teaching_ends_at": "2016-01-10",
"first_week_parity": "odd",
"hour_duration": 45,
"hour_starts": [
"07:30", "08:15", "09:15", "10:00", "11:00", "11:45",
"12:45", "13:30", "14:30", "15:15", "16:15", "17:00",
"18:00", "18:45", "19:45"
],
"periods": [
{
"type": "teaching",
"irregular": false,
"starts_at": "2015-10-05",
"ends_at": "2015-12-20",
"first_week_parity": "odd"
},
{
"type": "teaching",
"irregular": true,
"starts_at": "2015-12-21",
"ends_at": "2015-12-21",
"first_week_parity": "even",
"first_day_override": "wednesday"
},
{
"type": "teaching",
"irregular": true,
"starts_at": "2015-12-22",
"ends_at": "2015-12-22",
"first_week_parity": "odd",
"first_day_override": "tuesday"
},
{
"type": "holiday",
"name": {
"cs": "Vánoční prázdniny",
"en": "Christmas Holidays"
},
"irregular": false,
"starts_at": "2015-12-23",
"ends_at": "2016-01-03"
},
{
"type": "teaching",
"irregular": false,
"starts_at": "2016-01-04",
"ends_at": "2016-01-10",
"first_week_parity": "even"
},
{
"type": "exams",
"irregular": false,
"starts_at": "2016-01-11",
"ends_at": "2016-02-20"
}
]
}
}
/schedule_exceptions:
description: Manage schedule exceptions
is: [ paged ]
get:
description: Get a collection of schedule exceptions.
responses:
200:
body:
application/json:
example: |
{
"schedule_exceptions": [
{
"id": 1,
"type": "CANCEL",
"name": "Výuka zrušena z důvodu nemoci",
"scope": {
"starts_at": "2014-10-07T00:00:00.000+02:00",
"ends_at": "2014-10-08T00:00:00.000+02:00",
"faculty": 18000,
"semester": "B141",
"courses": [ "MI-RUB" ],
"timetable_slots": null
}
},
{
"id": 7,
"type": "ROOM_CHANGE",
"name": "MI-MPI - přednáška 24. 9. 2014 přesunuta do T9:105",
"scope": {
"starts_at": "2014-09-24T00:00:00.000+02:00",
"ends_at": "2014-09-25T00:00:00.000+02:00",
"faculty": 18000,
"semester": "B141",
"courses": null,
"timetable_slots": [ 392651000 ]
},
"options": {
"room_id": "T9:105"
}
}
],
"meta": {
"count": 2,
"offset": 0,
"limit": 20
}
}
/{id}:
uriParameters:
id:
description: ID of the schedule exception
required: true
get:
description: Get a schedule exception with the specified ID.
responses:
200:
body:
application/json:
example: |
{
"schedule_exceptions": {
"id": 7,
"type": "ROOM_CHANGE",
"name": "MI-MPI - přednáška 24. 9. 2014 přesunuta do T9:105",
"scope": {
"starts_at": "2014-09-24T00:00:00.000+02:00",
"ends_at": "2014-09-25T00:00:00.000+02:00",
"faculty": 18000,
"semester": "B141",
"courses": null,
"timetable_slots": [ 392651000 ]
},
"options": {
"room_id": "T9:105"
}
}
}
/semesters:
is: [ paged ]
securedBy: [ oauth2 ]
get:
description: This resource is **DEPRECATED,** use `/faculties/{facultyId}/semesters` instead.
queryParameters:
faculty:
description: Filter semesters by faculty id
type: integer
required: false
responses:
200:
body:
application/json:
/{faculty_semester}:
securedBy: [ oauth2 ]
uriParameters:
faculty_semester:
description: Faculty code and semester code connected with a dash.
pattern: "[0-9]{5}-[AB][0-9]{2}[12]"
example: 18000-B142
required: true
get:
description: >
This resource is **DEPRECATED,** use `/faculties/{facultyId}/semesters/{code}` instead.
responses:
200:
body:
application/json:
/search:
is: [ paged ]
securedBy: [ oauth2 ]
get:
description: >
Seach courses, people and rooms with the queried string in ID or title.
This resource is designed especially for an instant search (aka result autosuggestion).
queryParameters:
q:
description: Search query
type: string
required: true
responses:
200:
body:
application/json:
example: |
{
"results": [
{
"id": "MI-RUB",
"title": "Programování v Ruby",
"type": "course"
},
{
"id": "rubyelis",
"title": "Ing. Elisia Ruby",
"type": "person"
}
],
"meta": {
"offset": 0,
"limit": 2
}
}