api_specification_template.md

Specification of the Web API for the Video-AG Website (v0.87).

Introduction

In this document we use a lot of URLs. Parameters which need to be replaced are put in {}. Anything inside and the braces need to be replaced with the actual argument. These are called URL Parameters.

The Base-URL is /api/{version}, where {version} must be a version id from below. All URLs in this document are relative to this Base-URL (Unless explicitly stated otherwise).

The versions are:

Version	id	Status
0	v0	In Development

HTTP Bodies, if present, are always JSON objects unless explicitly stated otherwise. We use tables to represent the json object structure:

Field	Type	Notes
id	int
something	?string	We don't know what it is

Example json object:

{
    "id": 42,
    "something": "asdfghjkl"
}

The Field is the name of the JSON Key. Type is the type of data. The type may have some additional indicators:

• A question mark indicates that the value is optional.
• An exclamation mark indicates that the value may only be present if the user is a moderator.
• A plus indicates that the field is directly modifiable

Some routes, marked as such, require a CSRF token. This token is set as a cookie csrf_token by POST /authentication/fsmpi or POST /authentication/status and must be included as the X-Csrf-Token HTTP Header in such requests.

On success, status code 200 OK is always returned unless otherwise noted. Response Body is always present. For status codes 4xx and 5xx the response contains an api_error (May not be present if the error happened in a proxy, etc.).

The changelog can be found at the end.

Site status

The current site status can be retrieved with GET /status. It can be in three states

• available: The site is running and all routes can be used
• readonly: The site cannot update any data. You can only call routes for which is specified:
  • 'This may be used while the site is read-only.'
• unavailable: The site is unavailable and the only route you can call is GET /status

Stored Objects

The API is based on a concept of stored objects. In their serialized json form these look exactly the same as non-stored objects. However, stored objects have an id which is contained in their serialized form. With this ID the configuration of an object can be fetched and modified. The configuration of an object lists the object's fields along with their types and the current values. This allows the configuration to dynamically add or remove fields without the fields being hardcoded. Some of these fields correspond directly to fields in the object's serialized form. Such fields are marked with a + in this documentation and can also be modified directly. Note that some restrictions from the field description may still apply, and that the configuration should be queried before editing. Some fields of the serialized json are not included in the object's configuration and vice-versa.

Currently, the following objects have a configuration: {{CONFIG_OBJECT_LIST}}

TODO parents TODO deleted TODO variants

The types of these fields are described in the field description. For most fields the field type is exactly the same as the value type. Currently, the only exception are object fields where the value is a stored object. The object type is specified in the field description and the configuration only expects/returns integer ids.

Routes

{{ROUTES_SPECIFICATION}}

Resources

Types

Type	Notes
int
float
boolean
string
datetime	A string which must be in format YYYY-MM-ddTHH:mm:ss.SSSZ (Year, Month, day, Hour, minute, second, millisecond, 'T' and 'Z' are literals) (Note that this is a UTC date time according to ISO 8601)

Additionally, the following objects may appear as the type of some field:

• view_permissions

Objects

{{OBJECTS_SPECIFICATION}}

api_error

Field	Type	Notes
error_code	id_string	Possible values are listed below
message	string	Human readable message
server	string	Name of the server which served the request

Possible error_code:

Code	HTTP Code	Notes
bad_request	400
method_not_allowed	405
malformed_json	400	Content-Type needs to be set to application/json
request_missing_parameter	400
request_invalid_parameter	400
unknown_request_path	400
internal_server_error	500
lecture_has_no_password	400
authentication_failed	403
authentication_not_available	503
unauthorized	401
csrf_token_invalid	403	CSRF token must be included as X-Csrf-Token Header
access_forbidden	403
rate_limited	429
unknown_object	404
object_error	400
modification_unexpected_current_value	409
too_many_suggestions	403
site_is_readonly	503
site_is_disabled	503
site_is_overloaded	503

Changelog

v0.87

• Added GET /stats/course/{course_id}

v0.86

• Updated ffmpeg_filter_graph_node
  • Added webm to file_format

v0.85

• Updated GET /stats/publish_medium/{publish_medium_id}
  • Added fields total_watched_seconds and view_count

v0.84

• Updated medium_metadata
  • Added field file_format

v0.83

• Updated GET /lecture/{lecture_id}/media_process_overview
  • Added is_automatic_media_process_scheduler_enabled field
  • Added process_sha256 field
• Updated POST /lecture/{lecture_id}/run_media_process_scheduler
  • Changed response to same format as run_source_file_sorter
• Updated ffmpeg_filter_graph_output_stream
  • Added crf field
• Updated media_process_target_producer
  • Added crf field for type rescale_video

v0.82

• Changed publish_medium
  • Removed field allow_download
  • Added field download_url

v0.81

• Added milliseconds to datetime type and clarified that it is in UTC.

v0.80

• Updated field_description
  • Added may_be_null for type media_process

0.79

• Added POST /job/status
• Updated POST /run_source_file_sorter
  • Added job_id
  • Renamed scheduled to scheduled_new
• Updated job
  • Renamed status to state

v0.78

• Added type logo_overlay to ffmpeg_filter_graph_node
• Updated type output_file of ffmpeg_filter_graph_node
  • Added field output_file
  • Changed field stream_graph_ids to contain a new object ffmpeg_filter_graph_output_stream
• Updated video_slide_row
  • Now is typed with types text (what previously everything was) and spacer
  • Added fields padding_top, padding_bottom, padding_left, padding_right
• Added is_authenticated to lecture

v0.77

• Renamed data to unknown_data of changelog_entry

v0.76

• Removed lecture_id, is_lecture_authenticated from POST /authentication/fsmpi. Not sure why this was here. The status already has that functionality
• Added POST /course/{course_handle}/watched/publish_medium/{publish_medium_id}
• Added GET /stats/publish_medium/{publish_medium_id}
• Added GET /stats/lecture/{lecture_id}
• Added float standard type

v0.75

• Renamed media_duration to media_duration_sec in lecture

v0.74

• Renamed field source_id of media_process_target_producer for all variants to input_id

v0.73

• Added separate object_list type to `field_description
  • object is only for a single object
  • is_list has been removed
• Added may_be_null for types datetime and object

v0.72

• Added media_duration to lecture
• Reworked field_description
  • Added has_default_value. A missing default_value and a null default_value no longer have a different meaning
  • Stored objects are now handled with their own type object instead of every object type being a field type
  • All types are now listed explicitly
  • Type enum has new field name (For translation keys)

v0.71

• Added allow_download and include_in_player to publish_medium

v0.70

• Added user_context to GET /job/{job_id}
• Added job_context to GET /lecture/{lecture_id}/media_process_overview

v0.69

• Changes in user
  • Removed field name
  • Added fields display_name, full_name, email

v0.68

• Added file_size to medium_metadata

v0.67

• Renamed GET /lecture/{lecture_id}
  • Now as GET /course/{course_id}/lecture/{lecture_id}
  • or GET /course/{course_handle}/lecture/{lecture_id}
  • With handle is preferred, since unlisted courses and their lectures can no longer be found by non-mods if the id is provided
• Also renamed PUT /lecture/{lecture_id}/chapter_suggestion
  • to PUT /course/{course_id}/lecture/{lecture_id}/chapter_suggestion
  • or PUT /course/{course_handle}/lecture/{lecture_id}/chapter_suggestion
• Removed job status finished_and_processed and failed_and_processed
• Media Process has been updated
  • Removed target_medium object
  • Added objects
    • medium_file (stored)
    • medium_metadata (stored)
    • ffmpeg_filter_graph_node (non-stored)
    • ffmpeg_filter_graph_stream_specifier (non-stored)
    • video_slide (non-stored)
    • video_slide_row (non-stored)
  • Renamed source_medium to source_file
    • Moved GET /source_media to GET /sorter_files
    • Removed fields file_metadata, file_size
    • Added field designated_medium_file_id
  • Changed media_process_target_producer object
    • Added type ffmpeg_filter_graph
    • Renamed type downscale_video to rescale_video
  • Changed publish_medium object
    • Now has medium_metadata instead of target_medium field
    • Added url field
  • Adjusted GET /lecture/{lecture_id}/media_process_overview
    • Now returns the new objects and also the process

v0.66

• GET /source_media is only for mods
• GET /lecture/{lecture_id}/media_process_overview is only for mods
• Added POST /run_source_file_sorter
• Added POST /lecture/{lecture_id}/run_media_process_scheduler
• Added GET /media_process_templates
• old_value of changelog_entry is no longer present if the entry was at creation
• publish_time of lecture is now only returned for mods
• Added name and process to media_process_template

v0.65

• Changes in target_medium
  • Renamed video_horizontal_resolution to horizontal_resolution
  • Renamed video_vertical_resolution to vertical_resolution
  • Added horizontal_resolution and vertical_resolution to thumbnail
  • Added image variant

v0.64

• Added GET /source_media
• Fixed source_id name of media_process_target_producer (Was documented as input_id)
• Added sample_thumbnail variant to media_process_target_producer
• Changes in source_medium
  • Added force_immediate_sort
  • Added lecture_id
  • Added status
  • Added tag
• Added GET /lecture/{lecture_id}/media_process_overview
• Changes in target_medium
  • Added input_data_sha256
  • Added is_produced
  • Added process_sha256
  • Added process_target_id
  • Added producer_job
  • Added to_be_replaced

v0.63

• Added file_metadata, file_modification_time, file_size to source_medium
• Added and renamed variables in target_medium

v0.62

• Removed thumbnail_url from lecture
• Added new variant thumbnail to target_medium
• Removed visible from source_medium (Only accessible by mods anyway)
• Added missing variant plain to featured and plain_audio to target_medium which were mentioned nowhere before

v0.61

• Renamed path to file_path in source_medium
• Added update_time to source_medium

v0.60

• In job
  • Renamed run_finish_time to run_end_time (to avoid confusing with finished status. This time is also set if failed)
  • Added on_end_event_data and on_end_event_type
• In source_medium
  • Added path, sha256, sorter_error_message, sorting_paused_due_to_recent_modification
• Completely redid media_process
• Renamed media_process_target to media_process_target_producer
  • Removed id
  • Added output_id
  • Changed tags list to a single tag

v0.59

• Changed entries_per_page maximum in GET /jobs to 100
• Changed response of GET /jobs
• Removed GET /events
• Removed event
• Removed cause_event_id from job
• Added cause_user_id to job
• Added GET /job/{job_id}

v0.58

• Renamed frame_rate_nominator to frame_rate_numerator in target_medium

v0.57

• Removed GET /diagnostics
• Added thumbnail_url to lecture
• Added url to target_medium

v0.56

• Added stored objects media_process_template, target_medium and source_medium
• Added non-stored object media_process, media_process_target
• Added GET /jobs
• Added GET /events
• Added user_context to GET /object_management/changelog
• Added target_medium to publish_medium

v0.55

• Removed all 'types' except int, boolean, string, datetime
  • Most other types were just some of the standard data types with some additional conditions/notes and only used once. These notes are now just wherever the type is used
• Changed allowed fields for configuration objects
• Changes in GET /search
  • Renamed courses_context to course_context
  • The search term may not have more than 20 words
• Removed GET /feedback?entries_per_page={entries_per_page}&page={page}, feedback_entry
• Changes in GET /object_management/changelog
  • Renamed URL parameter field to field_id
  • URL parameter field_id may now be set even if the object_type is missing
  • Added URL parameter user_id
• Removed GET /sorter/log, DELETE /sorter/error_log/{log_id}, sorter_log_entry, sorter_error_log_entry
• Removed GET /jobs, DELETE /job/{id}, POST /job/{id}/action, job, worker
• Removed announcement_configuration, featured_configuration, course_configuration, lecture_configuration
  • Added object_configuration instead (Format is exactly the same)
• Removed homepage object. This is now an anonymous response object of GET /homepage
  • Renamed courses_context to course_context
  • Renamed new_lectures to latest_lectures
• Changes in announcement
  • Removed is_currently_visible, has_expired
  • Added publish_time, expiration_time, visible
  • Renamed visibility to page_visibility
• Changes in changelog_entry
  • object_type and object_id are now for all variants
  • object_type may be for type which no longer exists (due to legacy values)
  • new_value and old_value no longer have types guaranteed to match the field's type (due to legacy values)
  • All fields for type unknown have been removed and a new json field data has been added
• Changes in chapter
  • Renamed is_visible to visible
• Changes in course
  • Renamed is_visible to visible
  • Renamed is_listed to listed
  • Renamed id_string to handle
  • topic is now directly modifiable
  • visible is now directly modifiable
  • Added allow_embed
  • Added internal_comment
• Changes in featured
  • id is now also returned if non-mod
  • Removed guarantees for display_priority. These might be added back later
  • Removed course_list type
  • Added course type
  • Renamed is_visible to visible
• Changes in field_description
  • Removed fields for long, url, datetime, lecture_id, user_id
  • Added enums
• Changes in lecture
  • Removed thumbnail_url (Will be added back later)
  • Removed livestream_url
  • Removed allow_embed (The course now has this field)
  • Renamed media_sources to publish_media
  • Renamed is_visible to visible
• Changes in media_source which is now named publish_medium
  • id is now also returned for non-mods
  • Removed quality, size, player_url, download_url. These will be added back later
  • Removed internal_comment
  • Renamed is_visible to visible
  • Renamed comment to title
• Removed media_quality
• Removed feedback_entry
• Changes in user_info which is now named user
  • Renamed id_string to handle

v0.54

• Added PUT /feedback/new, GET /feedback?entries_per_page={entries_per_page}&page={page}
• Added feedback_entry object

v0.53

• Changed type of course_id_string to regex. Added forbidden values.

v0.52

• Added error code site_is_overloaded

v0.51

• Added server_name to GET /status

v0.50

• Removed GET /announcements
• Updated GET /status. Among other things, this now returns the announcements
• Changed name of error type authentication_servers_not_available to authentication_not_available
• Added error types site_is_readonly and site_is_disabled
• Added GET /is_running

v0.49

• Added GET /status

v0.48

• Removed PUT /job/new/{type}
• Removed POST /sorter/run

v0.47

• Removed GET /object_management/{object_type}/{object_id}/{field_id}/changelog
• Removed GET /object_management/{object_type}/{object_id}/changelog
• Added query parameters to GET /object_management/changelog instead
• Update type unknown of changelog_entry:
  • unknown_type -> unknown_object_type
  • old_value -> param1 (May be null)
  • new_value -> param2

v0.46

• Type url may be type of field.

v0.45

• Removed permission object
• Removed permissions from the configurations of courses and lectures
• Added view_permissions object which may appear as the type of some field
• may_be_null may now only appear in field_description of type datetime, lecture_id or user_id
• duration and timestamp may no longer appear as the type of some field

v0.44

• Added expected_current_values to PATCH /object_management/{object_type}/{object_id}/configuration (and accordingly to POST /object_management/modify_many)
• Added modification_unexpected_current_value error code

v0.43

• Added parent_type and parent_id to changelog_entry of type creation

v0.42

• Added worker object. Added workers field to GET /jobs
• Removed POST /job/{id}/restart, POST /job/{id}/cancel and POST /job/{id}/copy
• Added POST /job/{id}/action instead

v0.41

• Added GET /jobs, PUT /job/new/{type}, DELETE /job/{id}, POST /job/{id}/restart, POST /job/{id}/cancel and POST /job/{id}/copy
• Added job object
• Added job_state and job_type types

v0.40

• Added GET /user/me/settings and PATCH /user/me/settings
• Added settings, settings_section and settings_entry object

v0.39

• Added sorter_log_entry and sorter_error_log_entry objects
• Added GET /sorter/log, DELETE /sorter/error_log/{log_id} and POST /sorter/run

v0.38

• Removed is_modifiable of field_description (All fields can be modified)
• Fields with default values may be omitted at creation now
• Added guarantees for the creation of some objects

v0.37

• CSRF token is now returned in a cookie instead of the response body

v0.36

• Added CSRF tokens. The token is returned by POST /authentication/status.
• CSRF token is required by:
  • GET /lecture_import/rwth_online/{rwth_course_id}
  • PATCH /object_management/{object_type}/{object_id}/configuration
  • POST /object_management/modify_many
  • PUT /object_management/{object_type}/new
  • DELETE /object_management/{object_type}/{object_id}
  • POST /object_management/{object_type}/{object_id}/resurrect
• Added error code csrf_token_invalid

v0.35

• Added POST /object_management/{object_type}/{object_id}/resurrect

v0.34

• Added error code rate_limited

v0.33

• Removed field_entry
• Added field_description and field_value instead. The format of the configuration endpoints and changelog_entry has changed accordingly.

v0.32

• Changes to changelog_entry format
• Added GET /object_management/{object_type}/{object_id}/changelog?entries_per_page={entries_per_page}&page={page}

v0.31

• Changed GET /{object_type}/{object_id}/configuration to GET /object_management/{object_type}/{object_id}/configuration
• Changed PATCH /{object_type}/{object_id}/configuration to PATCH /object_management/{object_type}/{object_id}/configuration
• Changed POST /objects/modify_many to POST /object_management/modify_many
• Changed GET /{object_type}/new/configuration to GET /object_management/{object_type}/new/configuration
• Changed PUT /{object_type}/new/create to PUT /object_management/{object_type}/new
• Changed DELETE /{object_type}/{object_id} to DELETE /object_management/{object_type}/{object_id}
• Changed GET /{object_type}/{object_id}/{field_id}/changelog to GET /object_management/{object_type}/{object_id}/{field_id}/changelog
• Changed GET /objects/changelog to GET /object_management/changelog

v0.30

• Updated GET /{object_type}/{object_id}/{field_id}/changelog
• Added GET /search?q={search_term}

v0.29

• Added GET /{object_type}/{object_id}/{field_id}/changelog
• Changed /lecture_import/rwthonline/{rwth_course_id} to /lecture_import/rwth_online/{rwth_course_id}

v0.28

• /lecture_import/list_document/{course_id} => /lecture_import/rwthonline/{rwth_course_id}
• Removed POST /lecture_import/calendar_export

v0.27

• Added GET /lecture_import/list_document/{course_id}
• Added POST /lecture_import/calendar_export

v0.26

• Added GET /objects/changelog?entries_per_page={entries_per_page}&page={page}

v0.25

• Allowed creation of chapter objects
• Added PUT /lecture/{lecture_id}/chapter_suggestion
• Added too_many_suggestions error type

v0.24

• Added allow_embed to lecture

v0.23

• Updated directly modifiable Fields. They are now indicated by a +
• Added legacy_announcement_type

v0.22

• Changed featured type text to plain (Because all types contain text)

v0.21

• Updated display_priority of featured to be unique and no longer nullable

v0.20

• Added DELETE /{object_type}/{object_id}

v0.19

• Changed type of courses in featured to array of int. Added courses to the courses_context of the homepage instead.

v0.18

• Renamed Object Types to Object Variants as this was confusing. Renamed type_fields to variant_fields and type to variant for this

v0.17

• Added POST /objects/modify_many

v0.16

• Added display_priority to featured (Also to Directly Modifiable Fields)

v0.15

• Added course_filter_criteria type
• id_string may no longer be type of field entry
• Added course_id_string type

v0.14

• Added GET /users

v0.13

• Reverted GET /announcement back to GET /announcements
• Reverted GET /course back to GET /courses

v0.12

• Added POST /authentication/moderator_logout

v0.11

• Added Object Modification API
• Added announcement_configuration, featured_configuration, course_configuration, lecture_configuration, permission and field_entry objects
• Added internal_comment to media_source
• Added unknown_object and object_error error types. Removed unknown_course and unknown_lecture error types.
• Changed GET /announcements to GET /announcement (for consistency)
• Changed GET /courses to GET /course (for consistency)
• Changed GET /courses/{course_id} to GET /course/{course_id} (for consistency)
• Changed GET /lectures/{lecture_id} to GET /lecture/{lecture_id} (for consistency)

v0.10

• Added id, is_currently_visible and has_expired to announcement object
• Added id and is_visible to featured object
• Added is_listed and is_visible to course object
• Added is_visible and internal_comment to lecture object
• Added id and is_visible to chapter object
• Added id and is_visible to media_source object
• Changed pattern for id_string from [a-z0-9_-]{1,100} to (?=.*[a-z_-])[a-z0-9_-]{1,100}
• Changed route GET /courses/{course_id}/lectures/{lecture_id} to GET /lectures/{lecture_id}
• Made lecture of featured nullable

v0.9

• Added user_info to response of POST /authentication/status

v0.8

• Added authentication_information to course object

v0.7

• Added bad_request and method_not_allowed error codes

v0.6

• Changed /authentication/start to /authentication/start_oauth
• Removed /authentication/login
• Added /authentication/password and /authentication/fsmpi instead

v0.5

• Changed moderator authentication type to fsmpi (To be consistent with authentication_methods).

v0.3

• GET /courses/{course_id}/lectures/{lecture_id} now accepts course id_string and includes the course

v0.2

• GET /courses returns map instead of array

v0.1

• Initial version