Kepler REST API

This is the documentation of the REST API of Kepler reservation system.

The API calls are callable with URL paths of form /call/[call_name], where [call_name] is the name of the API call. All API calls return a standard result as JSON possibly with some custom fields. The result looks like the following:

{
    "timestamp": "2015-04-28T14:56:28.482545",
    "status": "ok"
}

The status field can have values "ok" or "error" depending on whether the call succeeded or failed.

All parameters and return values that represent time are strings in ISO-8061 format.

add_notice_board_note

The call adds a new note to the notice board.

Parameters

  • lang: The language part of the locale name in which the note is written. If it is not specified, the current session language is used. (optional)
  • message: The message of the note. (optional)
  • title: The title of the note. (optional)

add_permission

The call adds the permissions to the role.

Parameters

  • permission_id_list: A list of the IDs of the permissions that are to be added.
  • role_id: The ID of the role that gets the permission(s) added.

add_reservation

The call adds a new reservation for the current user.

Parameters

  • note: Note that is added to the reservation. (optional)
  • time_slot_id: The ID of the time slot for which the reservation is made.
  • unit_group_id: The ID of the unit group which the reserved unit belongs to.
  • unit_id: The ID of the unit that will be reserved.
  • user_group_id: The ID of the user group for which the reservation is made.

add_resource

The call adds a new resource to the system.

Parameters

  • description_en: The description of the resource in English. (optional)
  • description_fi: The description of the resource in Finnish. (optional)
  • name_en: The name of the resource in English (optional)
  • name_fi: The name of the resource in Finnish (optional)
  • statuses: The list of statuses for the resource. The list must contain objects that have status_id and count. (optional)

add_role

The call adds a new role to the system.

Parameters

  • name_en: The name of the role in English.
  • name_fi: The name of the role in English.
  • unit_type_id: The ID of the unit type the role is tied to. (optional)

add_role_to_user

The call adds the role(s) to the user.

Parameters

  • role_id_list: A list of the IDs of the roles that are to be added.
  • user_id: The ID of the user who get the role(s) added.

add_time_slot

The call adds a new time slot to the system.

Parameters

  • end_time: Specifies the end time of the time slot.
  • max_reservations: Specifies the maximum number of reservations that can be made for the time slot.
  • start_time: Specifies the start time of the time slot.
  • time_slot_supervisor_id_list: The list of ID(s) of the supervisor(s) of the time slot.
  • unit_type_id: Specifies the ID of the unit type of the created time slot.

add_unit

The call adds a new unit to the system.

Parameters

  • description_en: The description of the unit to be added in English. (optional)
  • description_fi: The description of the unit to be added in Finnish. (optional)
  • max_user_group_size: The maximum number of users that can belong to a group to make a reservation for the unit.
  • name_en: The name of the unit to be added in English. (optional)
  • name_fi: The name of the unit to be added in Finnish. (optional)
  • resources: A list of resources and their count that the unit shall have after the call. In other words, the old resources are replaced by the new ones. (optional)

add_unit_group

The call adds a new unit group to the system.

Parameters

  • name_en: The name of the unit group to be added in English. (optional)
  • name_fi: The name of the unit group to be added in Finnish. (optional)
  • unit_type_id: The ID of the unit type of the unit group to be added.
  • units: A list of unit IDs and qualifier strings that the unit group shall have after the call. (optional)

add_user_group

The call creates a new user group.

Parameters

  • description: The description of the user group. (optional)
  • member_id_list: The list of the user IDs of the group members.
  • name: The name of the user group.

delete_permission

The call removes the permissions from the role.

Parameters

  • permission_id_list: A list of the IDs of the permissions that are removed.
  • role_id: The ID of the role that gets the permission(s) removed.

delete_reservation

The call deletes the specified reservation.

Parameters

  • reservation_id: The ID of the reservation to be deleted.

delete_resource

The call deletes the specified resource.

Parameters

  • resource_id: The ID of the resource that will be deleted.

delete_role_from_user

The call removes the role(s) from the user.

Parameters

  • role_id_list: The list of the IDs of the roles that are to be removed.
  • user_id: The ID of the user who get the role(s) removed.

delete_time_slot

The call deletes the specified time slot. All reservations that have been made for the time slot are canceled.

Parameters

  • time_slot_id: The ID of the time slot to be deleted.

delete_unit

The call deletes a unit.

Parameters

  • unit_id: The ID of the unit that will be deleted. (optional)

delete_unit_group

The call deletes a unit group.

Parameters

  • unit_group_id: The ID of the unit group that will be deleted. (optional)

delete_user_group

The call to delete an existing user group.

Parameters

  • group_id: The ID of the group to be deleted.

edit_notice_board_note

Edits the specified notice board note.

Parameters

  • lang: The language part of the locale name in which the note is written. If it is not specified, the current session language is used. (optional)
  • message: The message of the note. (optional)
  • note_id: The ID of the note to be edited.
  • title: The title of the note. (optional)

edit_resource

The call edits the specified resource.

Parameters

  • description_en: The description of the resource in English. (optional)
  • description_fi: The description of the resource in Finnish. (optional)
  • name_en: The name of the resource in English. (optional)
  • name_fi: The name of the resource in Finnish. (optional)
  • resource_id: The ID of the resource that is edited.
  • statuses: The list of statuses for the resource. The list must contain objects that have status_id and count. (optional)

edit_unit

The call edits an existing unit.

Parameters

  • description_en: The description of the unit to be added in English. (optional)
  • description_fi: The description of the unit to be added in Finnish. (optional)
  • max_user_group_size: The maximum number of users that can belong to a group to make a reservation for the unit. (optional)
  • name_en: The name of the unit to be added in English. (optional)
  • name_fi: The name of the unit to be added in Finnish. (optional)
  • resources: A list of resources and their count that the unit shall have after the call. In other words, the old resources are replaced by the new ones. (optional)
  • unit_id: The ID of the unit that will be edited. (optional)

edit_unit_group

The call edits an existing unit group.

Parameters

  • name_en: The name of the unit group to be added in English. (optional)
  • name_fi: The name of the unit group to be added in Finnish. (optional)
  • unit_group_id: The ID of the unit group that will be edited.
  • unit_type_id: The ID of the unit type of the unit group to be added. (optional)
  • units: A list of unit IDs and qualifier strings that the unit group shall have after the call. (optional)

edit_user_group

The call edits the existing user group.

Parameters

  • description: The description of the user group. (optional)
  • group_id: The ID of the user group to be edited.
  • group_owner_id: The user ID of the group’s new owner. (optional)
  • name: The name of the user group. (optional)

get_calendar_events

The call returns the calendar events of the current user. The events can be filtered with time span parameters.

Parameters

  • end_time: The end point of the time span filter. (optional)
  • start_time: The start point of the time span filter. (optional)
  • user_group_id: The user group id of the group whose calendar events are to be returned. (optional)

get_notice_board

The call returns the list of notice board messages.

get_notice_board_notes

The call returns the list of notice board messages containing information needed to edit them.

get_permission_roles

The call returns the list of all the permissions and the roles that have the permissions.

get_reservation_ical

The call returns information regarding the reservation in iCal format.

Parameters

  • reservation_id: The ID of the reservation which is to be returned (optional)

get_reservations_user

The call returns the reservations of the current user. If no parameters are specified, all reservations are returned. If parameters are specified they define the time span of the reservations returned.

Parameters

If the parameters are empty or null, all of the user’s reservations are returned. If either of the time span end points are null, the span is not restricted by that end point.

  • end_time: The end of the time span of returned reservations (exclusive). (optional)
  • start_time: The start of the time span of returned reservations (inclusive). (optional)

get_resources

The call returns the list of all resources and their statuses. Even the resources that have zero for the count are returned. All statuses are sorted by the status_id field.

get_role_users

The call returns a list of all of the roles and the users having those roles.

get_time_slot_edit_info

The call returns the information needed in the time slot adding and editing view.

get_time_slot_events

The call returns the list of time slot events optionally filtered by a time span and the specified unit.

Parameters

  • end_time: The time span filter end point (optional)
  • start_time: The time span filter start point (optional)
  • unit_id: Filters the returned time slots by the unit ID. Only the time slots that can have reservation made for the specified unit are returned. (optional)
  • unit_type_id: Filters the returned time slots by the unit type. (optional)

get_time_slots

The call returns the list of time slots optionally filtered by a time span and the study level.

Parameters

  • current_user: True, if only current user’s supervision shifts are to be returned. (optional)
  • end_time: The time span filter end point. Default is a month forwards from now. (optional)
  • only_active: True, if only active reservations are to be returned (i.e. no cancelled reservations are returned). (optional)
  • start_time: The time span filter start point. Default is a week backwards from now. (optional)
  • supervisor_id: Filters the returned time slots by the user ID of the user who is a supervisor on the time slot. (optional)
  • time_slot_id: If specified, the call returns only the time slot with the specified ID. (optional)

get_unit_groups

The call returns list of unit groups from the database.

get_units

The call returns from the database list of units. Additionally, the call returns the list of all unit types in the system.

Example

An example of the result of the call is given below.

{
  "unit_types": [
    {"unit_type_name": "Subject related studies", "unit_type_id": 2},
    ...
  ],
  "units": [
    {
      "unit_id": 3,
      "unit_group_id": 4,
      "description": null,
      "name": "Steam pressure and heat of vaporization",
      "qualifier": "2",
      "unit_group": "FYSA241",
      "unit_type_name": "Subject related studies",
      "unit_type_id": 2
    },
    ...
  ]
}

get_units_editable

The call returns the list of units from the database with information needed for editing the units.

get_user_groups

The call returns the list of user groups that the current user belongs to. The list of other group members is also returned.

get_user_info

The call returns the information of the current user.

get_users

The call returns a list of users that match the search (or list of all users if no search parameters are provided).

Parameters

  • account_name: The account name used for searching users. (optional)
  • email: The email used for searching users. (optional)

hide_notice_board_note

The call hides the specified note of the notice board.

Parameters

  • note_id: The id of the note to be hidden.

remove_user_group_member

The call removes the given member from the specified user group.

Parameters

  • group_id: The ID of the user group to be edited.
  • user_id: The ID of the user that should be removed from the group.

search_user

The call returns the user that matches the search string. If no user is found the call returns null. Note that at most one user that matches exactly to the specified search string is returned.

Parameters

  • search_string: The email or account name used for searching a user.

Example

If the search string matches a user, the result would look like the following:

{
    "timestamp": "...",
    "status": "ok",
    "user": {
        "id": 3,
        "jyu_account": "...",
        "last_name": "...",
        "first_names": "...",
        "call_name": "...",
        "user_info": [ ... ],
        "roles": [ ... ]
    }
}

Otherwise, if no matching user is found, the result is

{
    "timestamp": "...",
    "status": "ok",
    "user": null
}

set_session_language

The call sets the session language based on the specified locale name.

Parameters

  • locale_name: The locale name of the language.

set_user_language

The call sets the user default language based on the specified locale name.

Parameters

  • locale_name: The locale name of the language.

show_notice_board_note

The call shows the specified note of the notice board.

Parameters

  • note_id: The id of the note to be shown.