*************** 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: .. code:: js { "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`__. __ http://en.wikipedia.org/wiki/ISO_8601 ---- 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. .. code:: js { "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: .. code:: js { "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 .. code:: js { "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.