Internal API
From ITR Wiki
Internal API
The internal API is for usage by the website of the ITR. It cannot be used from external websites, unless the flag ENABLE_CORS in the file instance/application.cfg is set to 'Y'. It is strongly discouraged to set this flag to 'Y' for anything else but developmnet systems.
The following API calls are available for the following roles (in case of doubt check the source code in the application.py file on github):
Overview functions and login functions
| Endpoint | Role | Description | Headers | Response codes | Supported operations |
|---|---|---|---|---|---|
| test | All | Standard test page | |||
| copyright | All | Return the copyright information for this ITR installation | 200 OK | Get | |
| companyname | All | Return the company name for this ITR installation | 200 OK | Get | |
| login | All | Login endpoint | UserID, Password, CompanyID (optional) | 200 OK or 401 user not found in case user is unknown or user id/password combination is not correct | Get |
| sendresetpassword | All | Send a reset password link via mail. The mail contains a URL with a token which is valid for 5 minutes. | UserID | 200 OK or 404 user not found | Post |
| resetpassword | All | Reset the password. In case the account is registered with multiple companies then all these passwords will be reset | UserID, Password, SessionID | 200 OK or 404 user not found or token invalid | Post |
| checktoken | All | Checks if the token is valid | UserID, Password, SessionID | 200 OK or 404 token invalid | Post |
| logout | All | Checks if the token is valid | SessionID | 200 OK or 404 token invalid | Post |
| audittrail | regular_office_user | returns audit trial | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| batteries | regular_office_user | returns batteries | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| educations | regular_office_user | returns educations | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| generatedreports | regular_office_user | returns generatedreports | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| groups | regular_office_user | returns groups | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| nationalities | regular_office_user | returns nationalities | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| organisations | regular_office_user | returns organisations | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| persons | regular_office_user & test_taking_user | returns persons. On post the login is created. For test_taking_user ONLY the DateOfLastTest field can be updated, the rest of the fields is ignored and no login is created. | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| sessiontests | regular_office_user | returns sessiontestsview, a combination of sessions, person, and sessiontests | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| sessiontestsview | regular_office_user | returns sessionsview, a combination of sessions and person | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| sessionsview | regular_office_user | returns sessiontests | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| groupsessionsview | regular_office_user | returns sessions | ID,Description,active,AllowedStartDateTime,AllowedEndDateTime,readycount,inprogresscount,donecount, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| sessions | regular_office_user and test_taking_user | returns sessions. for test_taking_user ONLY the sessions of the test taking user are returned. | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| reportdefinitions | regular_office_user | returns reportdefinitions | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| companies | master_user | returns companies | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| creditgrants | regular_office_user | returns creditgrants | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| creditusages | regular_office_user | returns creditusages | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| creditusagespermonth | regular_office_user | returns creditusages aggregated per month | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| datagathering | regular_office_user | returns datagathering | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| rightstemplates | regular_office_user | returns rightstemplates | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| logins | regular_office_user | returns logins | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| tokens | master_user | returns tokens | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| systemsettings | regular_office_user | returns systemsettings which are NOT protected. | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| screentemplates | test_taking_user | returns screentemplates | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| tests | regular_office_user | returns tests | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
| translations | All | returns available translations | SessionID, CompanyID, StartPage, PageSize, Sort (optional), IncludeMaster, IncludeClient, SearchField (optional), TimeZoneOffset, Filter (optional) | 200 OK or 404 token invalid | Get |
Detail functions (view source code for exact implementation)
| Endpoint | Role | Description | Headers | Response codes | Supported operations |
|---|---|---|---|---|---|
| /audittrail/<identity> | regular_office_user, Delete only for master_user | returns audit trial entry information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /batteries/<identity> | regular_office_user | returns battery information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /educations/<identity> | regular_office_user | returns education information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /generatedreports/<identity> | regular_office_user | returns generatedreport information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /groups/<identity> | regular_office_user | returns group information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /nationalities/<identity> | regular_office_user | returns nationality information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /persons/<identity> | regular_office_user | returns person information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /sessiontests/<sessionid> | regular_office_user | returns sessiontest information for the indicated session | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get |
| /sessiontests/<sessionid>/<identity> | regular_office_user | returns specific sessiontest information for the indicated session | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /sessionteststaking/<sessionid> | test_taking_user | returns sessiontest information for the indicated session, limited for this test taking user | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get |
| /sessionteststaking/<sessionid>/<identity> | test_taking_user | returns specific sessiontest information for the indicated session, limited for this test taking user | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post |
| /sessions/<identity> | test_taking_user, Delete only for regular_office_user | returns session information. If test_taking_user limited for this test taking user | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /sessions/<identity>/groupmembers | regular_office_user | returns group member information. | ID,EMail,FirstName,Initials, LastName,TitlesBefore,TitlesAfter, EducationID,OrganisationID, NationalityID,PreferredLanguage,Sex,DateOfLastTest, BirthDate,CompanyID, Active,ManagedByUserID | 200 OK or 404 token invalid | Get, Post, Delete |
| /reportdefinitions/<identity> | regular_office_user | returns reportdefinition information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /companies/<identity> | master_user | returns company information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /creditgrants/<identity> | regular_office_user, Post/Delete for master_user only | returns credit grant information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /creditusages/<identity> | regular_office_user, Post/Delete for master_user only | returns credit usage information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /datagathering/<identity> | regular_office_user | returns data gathering information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /rightstemplates/<identity> | regular_office_user, Post/Delete for organisation_supervisor only | returns template information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /logins/<identity> | test_taking_user, Post/Delete for regular_office_user only | returns login information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /logins/currentuser/companies | test_taking_user | returns login information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get |
| /logins/currentuser/changepassword | Any office user | Changes the password | SessionID, CompanyID, IncludeMaster, IncludeClient, old_password, new_password | 200 OK or 404 token invalid | Post |
| /tokens/<identity> | master_user | returns toekn information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /tokens/<identity>/<newcompany> | master_user | Switch the token to another company | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Post |
| /systemsettings/<identity> | Any office user | returns or updates a system setting. Protected parameters can ONLY be set by the supervisor. Parameters in the master database can ONLY be set by the master user. | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /screentemplates/<identity> | test_taking_user, Post/Delete for test_screen_template_author only | returns screen template information | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /tests/<identity> | test_taking_user, Post/Delete for test_author only | returns test information. test_taking_user does NOT get the fields norms, docuements, scorerules, graphs, requiredpars* | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /files/<company_id>/<maintainingObjectIdentity>/<fileType> | master_user or organisation_supervisor_user or author_user or test_taking_user, Delete NOT for test_taking_user | returns list of files for this test or object | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Delete |
| /filecopy/<maintainingObjectIdentity_src>/<maintainingObjectIdentity_dst> | master_user or organisation_supervisor_user or author_user | Copies the folder with media for all media types | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Post |
| /files/<company_id>/<maintainingObjectIdentity>/<fileType>/<fileId> | All, Post/Delete only for master_user or organisation_supervisor_user or author_user | get, update or delete the file | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post, Delete |
| /translations/<langcode> | All, Post/Delete for master_user or translator_user only | returns translation file or posts new translations for translation to the indicated language | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid | Get, Post |
| /sendmail | All office users | Sends a mail | SessionID, CompanyID, IncludeMaster, IncludeClient | 200 OK or 404 token invalid or 500 in case of mail error | Post |
