THIS SYSTEM IS USING THE REST-CONCEPT! THE USED FRONTEND IS NEVER PERMANENTLY CONNECTED TO THE BACKEND!
As a result, the credentials (name and password) OR a valid token must always be delivered in the header of the request for authentication!
The credentials have to be encoded, according to the Basic-Authentication standards. If this is not the case, the server will just return a 401 "unauthorized"-message!
If the logged in user does not posses the rights for executing the method at a given endpoint, there will be a 403-message as return value.
Eg.: A user without admin-rights tries to delete another user.
The Backend is using a library called Jackson, which maps the JSon to objects and vice versa. This means, the fields in the JSon-data MUST match the fields of the class used in CrAc. Information for that is provided down below in the details for each endpoint.
IMPORTANT: Not all fields have to be filled in! If only the name of the user should be changed, that is the only information that has to be sent via JSon. The Jackson-library takes all information sent and creates an object where it fills in all the fields it has provided data for, as long as this data does match the class-description.
In summary: Not all fields have to be sent via JSon, but the data sent MUST match the possible fields.
Get a valid token for the system and confirm your user
GET /user/login
->the name and password have to be added in the header as the basic-authentication
If the name and password transferred in the header are correct:
{
"success": "true",
"action": "create_token",
"id": "1",
"user": "user1",
"token": "r84r42cu9vs78jvj389cuj4cac",
"roles": [
{
"id": 1,
"name": "ADMIN",
"mappedPermissionTypes": [],
"mappedUser": [
1
]
}
]
}
else the standard unauthorized-message will appear:
{
"status": 401,
"error": "Unauthorized"
}
If the user already has a valid token, the system will output it and return a message that reminds the user, that he is already logged in.
Now, that the user is confirmed, there is another option for authenticating to endpoints, the token.
The value of the token return by this endpoint can just be added to the header of the request in the custom-field "Token". If it's valid, the system will act like the user is sending his actual name and password.
Delete your token
GET /user/logout
Either a success or a failure-message, depending on the VALID (through basic authentication) user already having a token or not.
This endpoint will delete the token that was created by calling the login-endpoint!
Before more funcionalities of the backend are explained in depth, the concept of it's competence-persistence needs to be explained.
Since they are not directly persisted in the DB of the backend but loaded from another, a synchronization needs to take place.
Additionally, the (now copied) competences need to be added to the intern storage-cache for performance-reasons.
These are the endpoints that allow those actions (also test-data can be created from here):
Copy test-data to the platform and fully synchronize all competences from KOMET
GET /synchronization/full
This endpoint includes all synchronization-functionality available!
Either a success or a failure-message.
Fully synchronize all competences from KOMET
GET /synchronization/competences
This endpoint copies all competence-related data from the KOMET-DB to the CrAc-DB and caches them to the intern storage. It only works if the databases are configured correctly!
Either a success or a failure-message.
Synchronize all competences from KOMET-DB to CrAc-DB
GET /synchronization/database
This endpoint copies all competence-related data from the KOMET-DB to the CrAc-DB.
Either a success or a failure-message.
Synchronizes the competences of the DB into the Competence-Storage of the application and caches the relations
GET /synchronization/intern
This endpoint copies and caches the competences data of the CrAc-DB into the intern storage.
Either a success or a failure-message.
Add filters to the configuration
GET /synchronization/filter
This endpoint adds matching-matrix-filters to the filter-configuration.
Either a success or a failure-message.
Copy test-data to the platform
GET /synchronization/data
This endpoint adds test-data to the platform.
Either a success or a failure-message.
Responses of Endpoints are presented in the following format:
The following JSON is just an example;
"type" contains the type of the data (eg Task, User etc).
"action" contains the action that is performed on the data.
"success" states if the action was a success or not.
If not, "errors" contains the different errors that happened.
"object" contains details about the object the action is performed on (after the action).
"meta" contains additional information.
{
"type": "Data-Type",
"rest_action": "CREATE",
"success": true,
"errors": [],
"object": {},
"meta": {}
}
These are the possible errors that can appear:
ACTION_NOT_VALID, ID_NOT_VALID, ID_NOT_FOUND, TASK_NOT_EXTENDABLE, PERMISSIONS_NOT_SUFFICIENT, ORGANISATIONAL_EXTENDS_SHIFT,
WORKABLE_EXTENDS_ORGANISATIONAL, WORKABLE_EXTENDS_WORKABLE, SHIFT_EXTENDS, USER_NOT_PARTICIPATING, TASK_NOT_STARTED, TASK_NOT_READY,
TASK_NOT_JOINABLE, TASK_ALREADY_IN_PROCESS, CHILDREN_NOT_READY, UNDEFINED_ERROR, START_NOT_ALLOWED, NOT_COMPLETED_BY_USERS,
QUANTITY_TOO_SMALL, QUANTITY_TOO_HIGH, QUANTITY_INCORRECT, DATASETS_ALREADY_EXISTS, JSON_READ_ERROR, JSON_MAP_ERROR, JSON_WRITE_ERROR, RESSOURCE_UNCHANGEABLE, TASK_IS_FULL, USERS_NOT_FRIENDS, WRONG_TYPE, ALREADY_FILLED, NOT_FOUND, TASK_HAS_OPEN_AMOUNT, CANNOT_BE_COPIED
Get all users
GET /user/all
An array containing all users
[
{
"id": 1,
"name": "testUser",
...
},
{
"id": 2,
"name": "AnotherUser",
...
}
]
Get one user by ID
GET /user/{id}
A user object with given id
{
"id": {id},
"name": "searchedUser",
...
}
Create a new user
POST /admin/user
{
"name":"test",
"password": "test",
"firstName":"TestHans",
"lastName":"TestName",
"phone":"234",
"email":"asd@asd"
}
Json-data, either a success or a failure message
Delete a user with given ID
DELETE /admin/user/{id}
Json-data, either a success or a failure message
Update the data of a user with given ID
PUT /admin/user/{id}
Updates a user by given ID
{
"name":"test",
"password": "test",
"firstName":"TestHans",
"lastName":"TestName",
"phone":"234",
"email":"asd@asd"
}
Json-data, either a success or a failure message
Get the data of the currently logged in user
GET /user
The object of the currently logged in user
{
"id": 3,
"name": "currentUser",
...
}
Update the data of the currently logged in user
PUT /user
Updates the currently logged in user
{
"name":"currentUser",
"password": "test",
"firstName":"TestHans",
"lastName":"TestName",
"phone":"234",
"email":"asd@asd"
}
Json-data, either a success or a failure message
Return a sorted list of elements with the best fitting users for the given task
GET user/find/{task_id}
[
{ "task": {
"id": 1,
"name": "task_1",
...
},
"assessment" : 0.5,
"doable" : true },
{ "task": {
"id": 2,
"name": "task_2",
...
},
"assessment" : 0.7 ,
"doable" : true },
...
]
Add a competence with given ID to the currently logged in user, likeValue and proficiencyValue are mandatory
{
"proficiencyValue": 50,
"likeValue": 50
}
POST competence/{competence_id}/add
Json-data, either a success or a failure message
Adjust the values of a user-competence connection
{
"proficiencyValue": 50,
"likeValue": 50
}
PUT competence/{competence_id}/adjust
Json-data, either a success or a failure message
Show all competences, that are and not yet connected available to a user
GET competence/available
[
{
"id": 1,
"name": "testCompetence",
...
},
{
"id": 2,
"name": "AnotherCompetence",
...
}
]
Remove a competence with given ID from the currently logged in user
DELETE competence/{competence_id}/remove
Json-data, either a success or a failure message
Returns a sorted list of elements with the best fitting tasks for the logged in user
GET task/find
[
{
"task": {
"id": 3,
"name": "Program a watering tool",
...
},
"assessment": 0.945
},
{
"task": {
"id": 2,
"name": "Water the roses",
...
},
"assessment": 0.54
},
{
"task": {
"id": 4,
"name": "Water the lillies",
...
},
"assessment": 0.54
}
]
Return a sorted list of a defined number of elements with the best fitting tasks for the logged in user
GET task/find/{number_of_tasks}
[
{
"task": {
"id": 3,
"name": "Program a watering tool",
...
},
"assessment": 0.945
},
{
"task": {
"id": 2,
"name": "Water the roses",
...
},
"assessment": 0.54
}
]
Issues a friend-request-notification to target user
GET user/{user_id}/friend
Json-data, a success
Shows the friends of the logged in user
GET user/friends
[
{
"id": 1,
"name": "friend1",
...
},
{
"id": 2,
"name": "friend2",
...
}
]
Unfriends target user
GET user/{user_id}/unfriend
Json-data, a success
Shows the relationships of the logged in user
GET user/relationships
[
{
"relatedUser": {
"id": 2,
"name": "user1",
...
},
"likeValue": 20,
"friends": true
},
{
"relatedUser": {
"id": 4,
"name": "user2",
...
},
"likeValue": -10,
"friends": false
}
]
Adds a role to the logged in User
PUT user/role/{role_id}/add
Json-data, a success
Removes a role from the logged in user
DELETE user/role/{role_id}/remove
Json-data, a success
Adds a role to target User
PUT admin/user/{user_id}/role/{role_id}/add
Json-data, a success
Removes a role from target user
DELETE admin/user/{user_id}/role/{role_id}/add
Json-data, a success
Adds an image to logged in user
POST user/image
The file must be posted as Multipart file! The file needs to have the key "file".
Json-data, a success or an error
Get the image of the logged in user
GET user/image
The picture, or an error as json:
{
"type": "NO_OBJECT",
"rest_action": "GET",
"success": false,
"errors": [
{
"name": "NOT_FOUND",
"cause": "bad_request"
}
],
"object": null,
"meta": {}
}
Get the image of target user
GET user/{user_id}/image
The picture, or an error as json:
{
"type": "NO_OBJECT",
"rest_action": "GET",
"success": false,
"errors": [
{
"name": "NOT_FOUND",
"cause": "bad_request"
}
],
"object": null,
"meta": {}
}
Returns all possible roles
GET /role
[
{
"id": 1,
"name": "USER",
"mappedPermissionTypes": [],
"mappedUser": [
1
]
},
{
"id": 2,
"name": "ADMIN",
...
},
...
]
Deletes the role with given id
DELETE /admin/role/{role_id}
Json-data, either a success or a failure message
Creates a new role
POST /admin/role
{
"name": "DUMMYROLE"
}
Json-data, either a success or a failure message
Updates the role with given id
PUT /admin/role/{role_id}
{
"name": "DUMMYROLE"
}
Json-data, either a success or a failure message
Returns all tasks affected by the chosen filters and the elasticsearch-query
POST /task
A given query reduces the pool of the found tasks to those that match the query by name or description.
A multitude of filters can be added, all with arbitrary [UNIQUE] parameters.
Here is an example for a possible posted JSON-Document:
{
"query": "here is my query",
"filters": [
{
"name": "FilterName1",
"params": [
{
"name": "paramtername1",
"value": paramter1
},
{
"name": "paramtername2",
"value": paramter2
}
]
},
{
"name": "FilterName2",
"params": [
{
"name": "paramtername",
"value": paramter
}
]
}
]
}
Existing filters:
The Date-Filter requires a combination of those four parameters to determine the time-intervall of the tasks
{
"name": "DateFilter",
"params": [
{
"name": "startDateMin",
"value": 1499205600000
},
{
"name": "startDateMax",
"value": 1499205600000
},
{
"name": "endDateMin",
"value": 1499205600000
},
{
"name": "endDateMax",
"value": 1499205600000
}
]
}
The Friend-Filter requires a username as name or both firstname and lastname to find a user and show tasks that this user is participating
{
"name": "FriendFilter",
"params": [
{
"name": "UserName",
"value": {
"firstName": "Max",
"lastName": "Mustermann"
}
},
{
"name": "Musteradmin",
"value": {
"firstName": "Martin",
"lastName": "Mustermann"
}
}
]
}
The Group-Filter requires the name and id of a group to find a certain group and will filter the tasks based on the restricting groups
{
"name": "GroupFilter",
"params": [
{
"name": "Group1",
"value": 1
},
{
"name": "Group2",
"value": "2"
}
]
}
The Creator-Filter requires the same parameters the Friend-Filter does but filters for tasks that have the given user as creator
{
"name": "CreatorFilter",
"params": [
{
"name": "UserName",
"value": {
"firstName": "Max",
"lastName": "Mustermann"
}
},
{
"name": "Musteradmin",
"value": {
"firstName": "Martin",
"lastName": "Mustermann"
}
}
]
}
The Competence-Filter requires arbitrary competence-ids to filter tasks for these competences
{
"name": "CompetenceFilter",
"params": [
{
"name": "id",
"value": 49524
},
{
"name": "id",
"value": 49517
}
]
}
The Geo-Filter requires the fields geoLat, geoLng as double and geoName, geoCountry, geoCountryA, geoMacroRegion, geoRegion, geoLocality as String. All tasks are filtered for matching fields, as long as they are not -1 (if it is a double) or "" (if it is a string). The attribute "logicAnd" can be set to true or false and connects all given attributes by And (if true) or by Or (if false).
{
"name": "GeoFilter",
"params": [
{
"name": "logicAnd",
"value": false
},
{
"name": "geoLat",
"value": -1.0
},
{
"name": "geoLng",
"value": 10.0
},
{
"name": "geoName",
"value": ""
},
{
"name": "geoCountry",
"value": ""
},
{
"name": "geoCountryA",
"value": ""
},
{
"name": "geoMacroRegion",
"value": ""
},
{
"name": "geoRegion",
"value": "Linz"
},
{
"name": "geoLocality",
"value": ""
}
]
}
[
{
"id": 1,
"name": "testTask",
...
},
{
"id": 2,
"name": "AnotherTask",
...
}
]
Returns target task and its relationship to the logged in user (if one exists) and updates the task if it's ready to start
GET /task/{task_id}
The information about the task and its relationships is in the meta-object
Add an attachment to target task
POST /task/{task_id}/attachment
The file must be posted as Multipart file! The file needs to have the key "file".
Json-data, a success or an error
Remove an attachment from target task
DELETE /task/{task_id}/attachment/{attachment_id}
Json-data, a success or an error
Get target attachment of target task
GET /task/{task_id}/attachment/{attachment_id}
Json-data, a success or an error
Updates the task with given id
PUT /task/{task_id}
{
"name": "testTask",
"description": "this is a test",
"location": "Vienna",
"startTime": "2000-01-01T00:30:00",
"endTime": "2000-01-01T01:00:00",
"minAmountOfVolunteers": 10,
"maxAmountOfVolunteers": 30
"taskType": "ORGANISATIONAL"
}
The following Task-Types can be chosen: ORGANISATIONAL, WORKABLE, SHIFT
ORGANISATIONAL: Can't be participated, only for organization purposes
WORKABLE: These are the tasks volunteers can be participate on
SHIFT: Workable tasks can be divided into shifts for marking time-spans on a task
Json-data, either a success or a failure message
Creates a new task
POST /admin/task
{
"name": "testTask",
"description": "this is a test",
"location": "Vienna",
"startTime": "2000-01-01T00:30:00",
"endTime": "2000-01-01T01:00:00",
"minAmountOfVolunteers": 10,
"maxAmountOfVolunteers": 30
"taskType": "ORGANISATIONAL"
}
The following Task-Types can be chosen: ORGANISATIONAL, WORKABLE, SHIFT
ORGANISATIONAL: Can't be participated, only for organization purposes
WORKABLE: These are the tasks volunteers can be participate on
SHIFT: Workable tasks can be divided into shifts for marking time-spans on a task
Json-data, either a success or a failure message
Deletes the task with given id
DELETE /admin/task/{task_id}
Json-data, either a success or a failure message
Returns all completed tasks of a user by participationType
GET /task/completed/{part_type}
{part_type} can be: PARTICIPATING, FOLLOWING, LEADING
Json-data, either a success or a failure message
Returns all completed projects
GET /task/completed
Json-data, either a success or a failure message
Returns all tasks of logged in user, divided in the TaskParticipationTypes, but only if they are not completed
GET task/type
"meta": {
"PARTICIPATING": [],
"LEADING": [
{
"id": 1,
"name": "test1",
...
}
],
"FOLLOWING": [
{
"id": 2,
"name": "test2",
...
}
],
"MATERIAL": [
{
"id": 3,
"name": "test3",
...
}
]
}
Adds target task to the open-tasks of the logged-in user or changes it's state; Choose either 'PARTICIPATING' or 'FOLLOWING'
PUT task/{task_id}/add/{state}
Json-data, either a success or a failure message
Removes the task with given id from the open-tasks of the currently logged in user
DELETE task/{task_id}/remove
Json-data, either a success or a failure message
Adds target competence to target task, it is mandatory to add the proficiency, importanceLvl and the mandatoryflag (as boolean)
{
"proficiency": 50,
"importance": 50,
"mandatory": true
}
POST /task/{task_id}/competence/{competence_id}/require
Json-data, either a success or a failure message
Adjust the values of a task-competence connection
{
"proficiency": 50,
"importance": 50,
"mandatory": true
}
PUT /task/{task_id}/competence/{competence_id}/adjust
Json-data, either a success or a failure message
Add multiple competences
Post a JSON-file with an array containing competence-ids and meta-data.
POST /task/{task_id}/competence/require
Each object can hold 4 different attributes:
competenceId (1 or higher)
neededProficiencyLevel (between 0 and 100)
importanceLevel (between 0 and 100)
mandatory (0 [for false] or 1 [for true])
[
{
"competenceId": 1,
"neededProficiencyLevel": 100,
"importanceLevel": 10,
"mandatory": 1
},
{
"competenceId": 2,
"neededProficiencyLevel": 100,
"mandatory": 0
},
{
"competenceId": 100,
"neededProficiencyLevel": 100
},
{
"neededProficiencyLevel": 100
}
]
{
"success": true,
"details": {
"1": {
"competence_status": "COMPETENCE_ASSIGNED"
"mandatory": "VALUE_NOT_VALID"
},
"2": {
"competence_status": "ALREADY_ASSIGNED_VALUES_ADJUSTED",
"importanceLevel": "NOT_ASSIGNED"
},
"100": {
"competence_status": "COMPETENCE_NOT_FOUND"
}
}
}
Json-data, either a success or a failure message
Overwrites all assigned competences with given competences
This endpoint works exactly as the one above ( .../require), except it overwrite all previously assigned competences!
Post a JSON-file with an array containing competence-ids and meta-data.
PUT /task/{task_id}/competence/overwrite
Json-data, either a success or a failure message
Removes a competence by given id to a task by given id
DELETE /task/{task_id}/competence/{competence_id}/remove
Json-data, either a success or a failure message
Add/Adjust multiple materials assigned to a task OR overwrite all materials assigned to a task
POST /task/{task_id}/material/multiple/{action}
As action, either add or overwrite can be put!
{
"name": "cake",
"description": "sweet baked food",
"quantity": 3
}
In details, the key of the object is the ID of the material:
{
"success": true,
"details": {
"1": {
"quantity": "DEFAULT_VALUE_ASSIGNED",
"material": "CREATED",
"description": "DEFAULT_VALUE_ASSIGNED"
},
"2": {
"material": "CREATED"
},
"3": {
"material": "CREATED",
"material_id": "ID_NOT_VALID"
}
}
}
The following messages can occur:
ACTION_NOT_VALID, PERMISSIONS_NOT_SUFFICIENT
ALREADY_EXISTS_VALUES_ADJUSTED, ID_NOT_VALID, CREATED, NOT_CREATED, NOT_ASSIGNED, DEFAULT_VALUE_ASSIGNED, VALUE_NOT_VALID,
Add a material to target task
POST /task/{task_id}/material
{
"name": "cake",
"description": "sweet baked food",
"quantity": 3
}
Json-data, either a success or a failure message
Update fields of target material on target task
PUT /task/{task_id}/material/{material_id}
{
"name": "cake",
"description": "sweet baked food",
"quantity": 3
}
Json-data, either a success or a failure message
Remove a material from target task
DELETE /task/{task_id}/material/{material_id}
Json-data, either a success or a failure message
Subscribe to a material of a task with a quantity, or change the quantity if already subscribed
PUT /task/{task_id}/material/{material_id}/subscribe/{quantity}
Json-data, either a success or a failure message
Possible failures:
QUANTITY_TOO_SMALL QUANTITY_TOO_HIGH
Unsubscribe to a subscribed material
DELETE /task/{task_id}/material/{material_id}/unsubscribe
Json-data, either a success or a failure message
Set the fullfilled-variable of target subscription
PUT /task/subscription/{subscription_id}/fullfilled/{fullfilled}
Json-data, either a success or a failure message
Sets the relation between the logged in user and target task to done, meaning the user completed the task
PUT /task/{task_id}/done/{done_boolean}
Json-data, either a success or a failure message
Returns an array with all tasks that contain given task_name in their name
GET /task/searchDirect/{task_name}
[
{
"id": 1,
"name": "task_name",
...
},
{
"id": 2,
"name": "x_task_name_y",
...
}
]
Creates a task, that is set as the child of the chosen existing task
GET /task/{supertask_id}/extend
{
"name": "testTask",
"description": "this is a test",
"location": "Vienna",
"startTime": "2000-01-01T00:30:00",
"endTime": "2000-01-01T01:00:00",
"minAmountOfVolunteers": 10,
"maxAmountOfVolunteers": 30
"taskType": "ORGANISATIONAL"
}
The following Task-Types can be chosen: ORGANISATIONAL, WORKABLE, SHIFT
ORGANISATIONAL: Can't be participated, only for organization purposes
WORKABLE: These are the tasks volunteers can be participate on
SHIFT: Workable tasks can be divided into shifts for marking time-spans on a task
These types exclude each other when trying to extend them illogically.
ORGANISATIONAL can only extend to another ORGANISATIONAL or WORKABLE,
WORKABLE can only extend multiple SHIFT-tasks,
every other extension is denied by the backend.
Json-data, either a success or a failure message
Copy target task
GET /task/{task_id}/copy
{
"date": "2500-01-01T00:30:00"
}
Json-data, either a success or a failure message
Updates the value of an task with an open amount of volunteers, based on the amount of volunteers on their child-tasks
GET /task/{task_id}/updateAmountOfVolunteers
Json-data, either a success or a failure message
Sets the TaskRepetitionState from once to periodic if possible, mandatory to add a date as json
GET /task/{task_id}/periodic/set
{
"year": 0,
"month": 0,
"day": 2,
"hour": 2,
"minute": 2
}
Json-data, either a success or a failure message
Resets the TaskRepetitionState from periodic to once
GET /task/{task_id}/periodic/undo
Json-data, either a success or a failure message
Issues an invite-notification to the target user or group
PUT /task/{task_id}/invite/{inv_type}/{inv_id}
{inv_type} can either be "user" or "group". {inv_id} then has to either be the user-id or the group-id. In case of a group, the task is added to the "invitedToTasks"-List of the given task.
Json-data, either a success or a failure message
Restrict a task to target group
PUT /task/{task_id}/restrict/group/{group_id}
Json-data, either a success or a failure message
Restrict a task to multiple groups and replace the groups already there
PUT /task/{task_id}/restrict/group/multiple
[
{
"id": 1
},
{
"id": 3
},
{
"id": 8
}
]
Json-data, either a success or a failure message
Change the state of target task; Choose either 'PUBLISHED', 'STARTED', or 'COMPLETED' For each state different prerequisite have to be fullfilled: NOT_PUBLISHED: Default state PUBLISHED: Only allowed when the task-fields are all filled STARTED: Only allowed when the parent task is started and if sequential, the previous task is completed COMPLETED: A task can only be completed when its children are all completed or if it has none
PUT /task/{task_id}/state/changeTo/{state_name}
Json-data, either a success or a failure message
Possible failures:
{
"success": false,
"error": "bad_request",
"cause": "REQUIREMENTS_NOT_FULLFILLED"
}
{
"success": false,
"error": "bad_request",
"cause": "SUB_ITEMS_NOT_READY"
}
{
"success": false,
"error": "bad_request",
"cause": "CHILDREN_NOT_READY"
}
{
"success": false,
"error": "bad_request",
"cause": "START_NOT_ALLOWED"
}
{
"success": false,
"error": "bad_request",
"cause": "TASK_NOT_READY"
}
{
"success": false,
"error": "bad_request",
"cause": "NOT_COMPLETED_BY_USERS"
}
{
"success": false,
"error": "bad_request",
"cause": "UNDEFINED_ERROR"
}
{
"success": false,
"error": "bad_request",
"cause": "PERMISSIONS_NOT_SUFFICIENT"
}
Force state-changes on task-trees that are not following the normal state-change rules; choose from 'unpublish' or 'complete'
PUT /task/{task_id}/state/force/{state_name}
Json-data, either a success or a failure message
Starts all tasks, that fullfill the prerequisites and are ready to starts
GET /task/updateStarted
Json-data, either a success or a failure message
Nominate someone as the leader of a task as creator
GET /task/{task_id}/nominateLeader/{user_id}
Json-data, either a success or a failure message
Returns the values for the enum taskParticipationType
GET /task/taskParticipationTypes
[
"PARTICIPATING",
"FOLLOWING",
"LEADING"
]
Returns the values for the enum taskState
GET /task/taskStates
[
"NOT_PUBLISHED",
"PUBLISHED",
"STARTED",
"COMPLETED"
]
Returns the values for the enum taskType
GET /task/taskTypes
[
"PARALLEL",
"SEQUENTIAL"
]
Returns all tasks, that are supertasks
GET /task/parents
[
{
"id": 1,
"name": "supertask_1",
...
},
{
"id": 2,
"name": "supertask_2",
...
}
]
Fulltext-queries all tasks with Elasticsearch and returns the found ones. If bound to competence-system, compares if tasks are doable
POST /task/elastic/query
{
"text": "This is a fulltext-query!"
}
[
{ "task": {
"id": 1,
"name": "task_1",
...
},
"assessment" : 0.5 },
{ "task": {
"id": 2,
"name": "task_2",
...
},
"assessment" : 0.7 },
]
Return a list of possible competence areas for the given task
GET task/{task_id}/competenceArea/suggest
[ { "id": 7364, "name": "Kochen", "description": "", "mappedCompetences": [] }, { "id": 7287, "name": "Kochen", "description": "", "mappedCompetences": [ 49545, 49548, 49547, 49544, 49546, 49553, 49555, 49550, 49551, 49554, 49552, 49549 ] } ]
Return a list of possible competences for the given task
GET task/{task_id}/competence/suggest
[ { "id": 49547, "name": "große Mengen an warmen Speisen zubereiten", "description": "Ich kann große Mengen an warmen Speisen zubereiten.", ... "competenceAreas": [ 7287 ], ... }, { "id": 49546, "name": "Backen", "description": "Ich kann einfache Kuchen backen.", ... "competenceAreas": [ 7287 ], ... }, { "id": 49544, "name": "Warme Speisen zubereiten", "description": "Ich kann warme Speisen zuzubereiten.", ... "competenceAreas": [ 7287 ], ... }, ... ]
Returns the competences of the currently logged in user, wrapped in the relationship-object
GET competence
[
{
"id": 16,
"user": 3,
"competence": {
"id": 6,
"name": "javascript-programming",
...
]
},
"likeValue": 1,
"proficiencyValue": 50
},
{
"id": 17,
"user": 3,
"competence": {
"id": 7,
"name": "php-programming",
...
]
},
"likeValue": 1,
"proficiencyValue": 50
},
...
]
Returns an array containing all competences
GET /competence/all
[
{
"id": 1,
"name": "testCompetence",
...
},
{
"id": 2,
"name": "AnotherCompetence",
...
}
]
Returns all competences that are related to target competence, ordered by it's relation-value
GET /competence/{competence_id}/related
Standard response, the related-competences are part of the meta-object
Returns target competence-topic-area and its mapped competences
GET /competence/area/{area_id}
Standard response, the related-competences are part of the meta-object
Returns all competence-topic-areas
GET /competence/area
Standard response, the related-competences are part of the meta-object
Returns a competence object with given id
GET /competence/{competence_id}
{
"id": {competence_id},
"name": "searchedCompetence",
...
}
Creates a new competence
POST /admin/competence
{
"name":"testCompetence",
"description": "this is a competence"
}
Json-data, either a success or a failure message
Deletes competence by given ID
DELETE /admin/competence/{competence_id}
Json-data, either a success or a failure message
Updates a competence by given ID
PUT /admin/competence/{competence_id}
{
"name":"testCompetence",
"description": "this is a competence"
}
Json-data, either a success or a failure message
Connects two competences via a type and additional values
POST /competence/{competence1_id}/connect/{competence2_id}/type/{type_id}
{
"uniDirection": true
}
Json-data, either a success or a failure message
These endpoints handle the filter-configuration of the User-Task-Allocation (the matrix-part). It consists of 3 different configurations, which can be handled sperately:
PreMatchingFilters, MatchingFilters and PostMatchingFilters.
For each endpoint the value {matching_type} can be set to "prematching", "matching" or "postmatching"!
Available filters for the categories:
prematching: GroupFilter, LoggedUserFilter
matching: LikeLevelFilter, ImportancyLevelFilter, ProficiencyLevelFilter, UserRelationFilter
postmatching: ClearFilter, MissingVolunteerFilter
####The standard configuration contains all filters once (they can be added multiple times if that is wanted)
Sets target configuration, based on the list of filters in the posted JSon-file
POST /filter/{matching_type}
{
"filters": [
{
"name":"ImportancyLevelFilter"
},
{
"name":"LikeLevelFilter"
},
{
"name":"ProficiencyLevelFilter"
},
{
"name":"LikeLevelFilter"
}
]
}
Json-data, either a success or a failure message when an invalid filter-name has been used.
Returns a list of all active filters of target configuration
GET /filter/{matching_type}/print
{
"success": "true",
"msg": "ProficiencyLevelFilter is available! LikeLevelFilter is available! UserRelationFilter is available! ImportancyLevelFilter is available! "
}
Clears (empties) the list of active filters of target configuration
DELETE /filter/{matching_type}
Json-data, a success
Restores the standard state of target filter-configuration
PUT /filter/{matching_type}/restore
Json-data, a success.
These endpoints handle already issued notifications for the most parts
Returns all notifications, which target the logged in user
GET /notification
[
{
"notificationId": "22517116313100323167",
"sender": {
"id": 1,
"name": "user",
"lastName": "user_last1",
"firstName": "user_first1"
},
"target": {
"id": 3,
"name": "ProellADMIN",
"lastName": "user_last2",
"firstName": "user_first2"
},
"task": {
"id": 2,
"name": "testTask",
"description": "this is a test",
...
},
...
},
{
"notificationId": "528924t6523027823167",
"sender": {
"id": 1,
"name": "user",
"lastName": "user_last1",
"firstName": "user_first1"
},
...
}
]
Returns all notifications in the system
GET /notification/admin
[
{
"notificationId": "22517116313100323167",
"sender": {
"id": 1,
"name": "user",
"lastName": "user_last1",
"firstName": "user_first1"
},
"target": {
"id": 3,
"name": "ProellADMIN",
"lastName": "user_last2",
"firstName": "user_first2"
},
"task": {
"id": 2,
"name": "testTask",
"description": "this is a test",
...
},
...
},
{
"notificationId": "528924t6523027823167",
"sender": {
"id": 1,
"name": "user",
"lastName": "user_last1",
"firstName": "user_first1"
},
...
}
]
Triggers the accept-method of the notification and deletes it
GET /notification/{notification_id}/accept
Json-data, either a success or a failure message
Triggers the deny-method of the notification and deletes it
GET /notification/{notification_id}/deny
Json-data, either a success or a failure message
These endpoints handle evaluations
Creates an evaluation (notification + entity) for the logged in user for target task
POST /evaluation/task/{task_id}/self
Json-data, either a success or a failure message
Creates an evaluation (notification + entity) for every user, participating in target task
POST /evaluation/task/{task_id}/all
Json-data, either a success or a failure message
Returns all evaluations of the logged in user
GET /evaluation
Json-data, either a success or a failure message
Resolves the evaluation. Updates the empty evaluation with sent data and deletes the notification
PUT /evaluation/{evaluation_id}
for current evaluation send these attributes with arbitrary values:
{
"likeValOthers": 0.5,
"likeValTask": 0.5
}
Json-data, either a success or a failure message
These endpoints handle groups
Get all groups
GET /group
Json-data, either a success or a failure message
Get the group with given ID
GET /group/{group_id}
Json-data, either a success or a failure message
Create a new group, creator is the logged-in user
POST /group
{
"name": "groupExample",
"description": "An example of a group",
"maxEnrols": 5
}
Json-data, either a success or a failure message
Delete the group with given ID
DELETE /group/{group_id}
Json-data, either a success or a failure message
Update the group with given ID
PUT /group/{group_id}
{
"name": "groupExample",
"description": "An example of a group",
"maxEnrols": 5
}
Json-data, either a success or a failure message
Add multiple users to a group
PUT /group/{group_id}/add/multiple
Multiple users can be added to a given group by posting them in one JSON-document like this:
[
{
"id": 1,
"name": user1
},
{
"id": 3,
"name": user3
},
{
"id": 8,
"name": user8
}
]
Json-data, either a success or a failure message
Add target user to a group
PUT /group/{group_id}/add/user/{user_id}
Json-data, either a success or a failure message
Removes target user from a group
DELETE /group/{group_id}/remove/user/{user_id}
Json-data, either a success or a failure message
In this section, changes and their dates are noted.
Role-System implemented -> see section Role-Endpoints The endpoint for the role-enums has been removed
Token-System implemented -> see section User-Endpoints for login (creation) and logout (destruction) with tokens The "check"-endpoint is not part of the readMe anymore, since it's depricated and will be removed soon, if used, change it to the "login"-endpoint
Endpoint-change -> Assigned competences of user now at the /competence-endpoint, all competences at the endpoint /competence/all
Endpoint-change -> A single task + task-user-relationship is available at the /user/task/{task_id}-endpoint
With the big changes to tasks, the following endpoints have been implemented:
GET /task/{task_id}/publish/ready/single -> NEW
GET /task/{task_id}/publish/ready/tree -> NEW
GET /task/{task_id}/done/{done_boolean} -> NEW
GET /task/updateStarted -> NEW
The following endpoints where changed:
GET /task/{task_id}/state/{state_name} -> FUNCTIONALITY CHANGED
PUT /admin/task -> from /task, now only usable with admin or editor permissions
GET /task/{task_id} -> FUNCTIONALITY CHANGED, now updates the task if it's ready to start
GET /user/task/{task_id}/{state_name} -> from /task/{task_id}/{state_name}
Change to how the amount of volunteers on tasks is handled
The attribute can be set to any positive number, meaning the concrete amount of volunteers, or to "0", meaning an infinite number
of volunteers can join the task. This "0" can also be updated to a concrete amount, based on the amount that's placed on the child-tasks:
GET /task/{task_id}/updateAmountOfVolunteers -> NEW
Change to the endpoint, that gets users for a specific task.
GET /task/{task_id}/findMatchingUsers -> from /task/findMatchingUsers/{task_id}
-> Competences are synchronized from the DB into the running system for performance-reasons now, and thus MUST be synchronized by hand if there is a change on KOMET! This can be done by calling the following endpoint with ADMIN-permissions:
GET /admin/sync -> NEW
A new filter-configuration has been added to the system.
These filters influence the matching between users and tasks and can be added and removed.
There are 4 filter-types at the moment:
LikeLevelFilter (changed matching-values based on the user's affection towards a competence), ImportancyLevelFilter (changed matching-values based on the importance of the competence), ProficiencyLevelFilter (changes matching-values based on the users proficiency and the tasks needed proficiency in a competence) and UserRelationFilter (changes the matching-values based on the relation of the searching user to already participating users).
Look up the filter-section of the readMe details to the endpoints.
A new endpoint returns a specified amount of best matches.
GET /user/findMatchingTasks/{number_of_tasks} -> NEW
Materials can now be assigned to tasks.
Endpoints for that are in the task-section.
GET /task/{task_id}/material/add -> NEW
GET /task/{task_id}/material/update/{material_id} -> NEW
GET /task/{task_id}/material/remove/{material_id} -> NEW
Materials can be subscribed to (with a quantity) by the logged in user.
Adding a material returns the material-id.
GET /task/{task_id}/material/{material_id}/subscribe/{quantity} -> NEW
GET /task/{task_id}/material/{material_id}/unsubscribe -> NEW
Look at the task-section for more info
Endpoints to set tasks ready-to-publish are removed, this is done automatically now!
TaskTypes have been added! More information in the endpoint for adding tasks
Error-Responses are updated, more information in the error-section!
The Task-Workflow has been removed from the ReadMe! It can be found on SVN/contact me for information
New Endpoints (especially important for competence-recommendation) :
GET /area
GET /area/{area_id}
GET /{competence_id}/related
More infos in the competence-section!
Endpoints that are changed :
OLD -> NEW
Competence-related:
GET /user/competence/{competence_id}/add -> POST /competence/{competence_id}/add (PARAMETERS NOW VIA JSON)
GET /user/competence/{competence_id}/adjust -> PUT /competence/{competence_id}/adjust (PARAMETERS NOW VIA JSON)
GET /user/competence/{competence_id}/remove -> DELETE /competence/{competence_id}/remove
GET /user/competence -> GET /competence (BOTH ENDPOINTS MERGED)
Task-related:
GET /user/task/{task_id} -> GET /task/{task_id} (BOTH ENDPOINTS MERGED)
GET /user/task -> GET /task/type
GET /user/task/{task_id}/{state_name} -> PUT /task/{task_id}/add/{state_name}
GET /user/task/{task_id}/remove -> DELETE /task/{task_id}/remove
GET /user/findMatchingTasks -> GET /task/find
GET /user/findMatchingTasks/{number_of_tasks} -> GET /task/find/{number_of_tasks}
GET /task/{task_id}/findMatchingUsers -> GET /user/find/{task_id}
POST /task/queryES -> POST /task/elastic/query
GET /task/{task_id}/competence/{competence_id}/require/{proficiency}/{importance}/{mandatory} -> POST /task/{task_id}/competence/{competence_id}/require (PARAMETERS NOW VIA JSON)
GET /task/{task_id}/material/{material_id}/remove -> DELETE /task/{task_id}/material/{material_id}/remove
GET /task/{task_id}/material/{material_id}/subscribe/{quantity} -> PUT /task/{task_id}/material/{material_id}/subscribe/{quantity}
GET /task/{task_id}/material/{material_id}/unsubscribe -> DELETE /task/{task_id}/material/{material_id}/unsubscribe
GET /task/{task_id}/competence/{competence_id}/remove -> DELETE /task/{task_id}/competence/{competence_id}/remove
GET /task/{task_id}/done/{done_boolean} -> PUT /task/{task_id}/done/{done_boolean}
GET /task/{task_id}/state/{state_name} -> PUT /task/{task_id}/state/{state_name}
Changes for a better integration of the evaluation-topic have been made:
New section for "Evaluation-Endpoints"!
Endpoints for calling completed tasks (for more information, see section "Task-Endpoints":
GET /task/completed/{part_type}
GET /task/completed
Endpoints for groups have been added:
New section "Group-Endpoints"!
Endpoint for inviting users to a task is now PUT /task/{task_id}/invite/{inv_type}/{inv_id}
Endpoint for restricting a task to different groups PUT /task/{task_id}/restrict/group/{group_id}
Endpoints for roles have changed --> see the "User-Endpoints"!
Major change for the "get all tasks"-Endpoints --> see the "Task-Endpoints" (first entry)!
New endpoints for adding and removing users to and from groups --> see "Group-Endpoints"
Information in notifications now consists of object and not just their ID! -> see "Notification-Endpoints"
API for changing task-states has changed -> see "Task-Section"
Endpoints for the uploading of picture for users added -> see "User-Section"
Endpoint for uploading of attachments for tasks and endpoint for copiing an archived task added -> see "Task-Section"
Change for task-endpoints:
GET task/type now returns differently named keys -> see "Task-Section"
New endpoint for setting material-subscriptions to fullfilled -> PUT task/subscription/{subscription_id}/fullfilled/{fullfilled}
Endpoints for images changed -> GET, ADD, DELETE removed since information is already available in the request-method
Endpoint for getting the image of any user added -> Get user/{user_id}/image
Rework of the filter-section!
New (and changed) endpoints for accessing the filter-configuration for the matching-process -> see "Filter-Section"
Changed endpoints for accessing materials on tasks -> ADD, UPDATE, REMOVE removed since information is already available in the request-method
POST /task/{task_id}/material/add -> POST /task/{task_id}/material
PUT /task/{task_id}/material/{material_id}/update -> PUT /task/{task_id}/material/{material_id}
DELETE /task/{task_id}/material/{material_id}/remove -> DELETE /task/{task_id}/material/{material_id}
Copyright 2017 CrAc syndicate (http://www.crac.at/project-facts/partners)
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.