diff --git a/README.md b/README.md
index b5cd15c..6437647 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,2 @@
# Yaptide developer documentation
+https://yaptide.github.io/for_developers/
diff --git a/docs/backend/openapi.yaml b/docs/backend/openapi.yaml
new file mode 100644
index 0000000..232395d
--- /dev/null
+++ b/docs/backend/openapi.yaml
@@ -0,0 +1,1373 @@
+openapi: 3.0.3
+info:
+ title: Yaptide Project Api Documentation
+ version: 1.0.0
+ description: Yaptide Project Api Documentation
+servers:
+ - url: http://localhost:5000
+paths:
+ /:
+ get:
+ security:
+ - basicAuth: [ ]
+ summary: Allows to check if server is alive
+ description: Allows to check if server is alive. If server is down it won't respond to this request
+ responses:
+ '200':
+ description: Successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# Authorisation Routes
+ /auth/register:
+ put:
+ summary: Allows registration of new users
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RegisterLoginRequest'
+ responses:
+ '201':
+ description: Returns message - User created
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '400':
+ description: Bad Request - Missing payload or keys in payload
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ /auth/login:
+ post:
+ summary: Allows to login the user - server sets refresh and access tokens in cookies
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RegisterLoginRequest'
+ responses:
+ '202':
+ description: Includes expiration time in milliseconds of new access tokens with message - Successfully logged in
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ access_exp:
+ type: integer
+ refresh_exp:
+ type: integer
+ '400':
+ description: Bad Request - Missing payload or keys in payload
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Forbidden - Invalid login or password
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ /auth/refresh:
+ get:
+ summary: Allows to refresh access token - server sets new access token in cookies
+ responses:
+ '200':
+ description: Includes expiration time in milliseconds of new access token
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ access_exp:
+ type: integer
+ '401':
+ description: Unauthorized - No token provided
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found or log in required
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ /auth/status:
+ get:
+ summary: Allows to retrieve logged in user information
+ responses:
+ '200':
+ description: Includes logged in user information, shown in example response below
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ username:
+ type: string
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required or token refresh required
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ /auth/logout:
+ delete:
+ summary: Allows to logout the user - server removes access and refresh tokens from cookies. If nobody was logged in then just nothing happens
+ responses:
+ '200':
+ description: User was successfully logged out
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# Keycloak auth Routes
+ /auth/keycloak:
+ post:
+ summary: Allows to login the user with keycloak credentials - server sets refresh and access tokens in cookies
+ description: At current state this endpoint works only with server running on C3
+ parameters:
+ - in: header
+ name: Authorization
+ schema:
+ type: string
+ required: true
+ description: keycloak token
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/KeycloakRequest'
+ responses:
+ '202':
+ description: Includes expiration time in milliseconds of new access token
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ access_exp:
+ type: integer
+ '400':
+ description: Bad Request - Missing payload or keys in payload
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Forbidden - No token provided
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# User Routes
+ /user/simulations:
+ get:
+ summary: Allows for getting user's simulations
+ parameters:
+ - in: query
+ name: page_size
+ schema:
+ type: integer
+ description: Specifies the page size from range [0,100] - incorrect or
+ non provided value will result in sending page with size 10
+ - in: query
+ name: page_idx
+ schema:
+ type: integer
+ description: Specifies the page index to be send - incorrect or non
+ provided value will result in sending page with index 0
+ - in: query
+ name: order_by
+ schema:
+ type: string
+ enum: [start_time, end_time]
+ description: Specifies the parameter by which pages are sorted, available are start_time or end_time
+ - incorrect or non provided value will result in sending page sorted by start_time
+ - in: query
+ name: order_type
+ schema:
+ type: string
+ enum: [ascend, descend]
+ description: Specifies the order in which pages are sorted, available are ascend or descend
+ - incorrect or non provided value will result in sending page sorted by ascend
+ responses:
+ '200':
+ description: Includes list of user's simulations
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ page_count:
+ type: integer
+ description: returns the number of available pages
+ simulations_count:
+ type: integer
+ description: returns the number of owned simulations
+ simulations:
+ description: is a list of simulations returned in requested page
+ type: array
+ items:
+ $ref: '#/components/schemas/Simulation'
+
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required or token refresh required
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ delete:
+ summary: Allows for deleting simulation.
+ parameters:
+ - in: query
+ name: job_id
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Simulation was succesfully deleted
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - User does not have permission to delete this simulation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - The simulation is currently running, needs to be canceled or completed before deletion
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Not Found - The simulation with the provided job_id does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ /user/clusters:
+ description: Returns available clusters
+ get:
+ summary: Allows for getting available clusters
+ responses:
+ '200':
+ description: Includes list of available clusters
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ clusters:
+ type: array
+ items:
+ type: object
+ properties:
+ cluster_name:
+ type: string
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required or token refresh required
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# Jobs Routes
+ /jobs:
+ get:
+ summary: Allows for getting job status from database.
+ description: Endpoint designed for getting periodical job status from database.
+ parameters:
+ - in: query
+ name: job_id
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Includes status of the job
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ job_state:
+ type: string
+ enum: [PENDING, RUNNING, COMPLETED, FAILED]
+ description: job state
+ job_task_status:
+ type: array
+ items:
+ $ref: '#/components/schemas/JobTaskStatus'
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required, token refresh required or job with provided ID does not belong to the user
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Job with provided ID does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '408':
+ description: Timeout
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ post:
+ summary: For updating simulation object in database and uploading error logs
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateJob'
+ responses:
+ '202':
+ description: Simulation updated
+ '501':
+ description: Error updating simulation
+ /jobs/direct:
+ post:
+ summary: Allows for submitting jobs to run directly on server.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ allOf:
+ - $ref: '#/components/schemas/JobsRequest'
+ - $ref: '#/components/schemas/Input'
+ responses:
+ '202':
+ description: Includes job_id and additional information about submited job
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ job_id:
+ type: string
+ message:
+ type: string
+ '400':
+ description: Bad Request - Missing payload or keys in payload
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required or token refresh required
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ get:
+ summary: Allows for getting job status and additional job's info. Available only for jobs run directly.
+ description: At current stage of development it does not provide any addtional features than GET method from '/jobs' route - it does the same thing but it is available only for jobs run directly.
+ parameters:
+ - in: query
+ name: job_id
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Includes status and additional information about the job
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ job_state:
+ type: string
+ enum: [PENDING, RUNNING, COMPLETED, FAILED]
+ description: job state
+ job_task_status:
+ type: array
+ items:
+ $ref: '#/components/schemas/JobTaskStatus'
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required, token refresh required or job with provided ID does not belong to the user
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Job with provided ID does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '408':
+ description: Timeout
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ delete:
+ summary: Allows for job cancelation. Available only for jobs run directly.
+ parameters:
+ - in: query
+ name: job_id
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Returns information about main job and subtasks' cancelation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/JobsDirectDeleteResponse'
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required, token refresh required or job with provided ID does not belong to the user
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Job with provided ID does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '408':
+ description: Timeout
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ /jobs/batch:
+ post:
+ summary: Allows for submitting jobs to run on SLURM.
+ description: This endpoint can be used only by keycloak authenticated users
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ allOf:
+ - $ref: '#/components/schemas/JobsRequest'
+ - $ref: '#/components/schemas/Input'
+ - $ref: '#/components/schemas/BatchOptions'
+ responses:
+ '202':
+ description: Includes job_id and additional information about submited job
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ job_id:
+ type: string
+ message:
+ type: string
+ sh_files:
+ type: object
+ description: contains sh files used by the job (additional info in response from '/jobs/batch')
+ properties:
+ submit:
+ type: string
+ description: submit is a file which prepares the environment and starts array and collect
+ array:
+ type: string
+ description: array is array job script which runs the simulation
+ collect:
+ type: string
+ description: collect is a script collecting results generated by simulation
+ submit_stdout:
+ type: string
+ description: submit_stdout is output generated by submit.sh (additional info in response from '/jobs/batch')
+ '400':
+ description: Bad Request - Missing payload or keys in payload
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required or token refresh required
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ get:
+ summary: Allows for getting job status and additional job's info. Available only for jobs run on SLURM.
+ description: This endpoint can be used only by keycloak authenticated users. It is recommended not to use it very often because of the high load it puts on the SLURM system.
+ parameters:
+ - in: query
+ name: job_id
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Includes status and additional information about the job
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ job_state:
+ type: string
+ enum: [PENDING, RUNNING, COMPLETED, FAILED]
+ description: job state
+ job_task_status:
+ type: array
+ items:
+ $ref: '#/components/schemas/JobTaskStatus'
+ sh_files:
+ type: object
+ description: contains sh files used by the job (additional info in response from '/jobs/batch')
+ properties:
+ submit:
+ type: string
+ description: submit is a file which prepares the environment and starts array and collect
+ array:
+ type: string
+ description: array is array job script which runs the simulation
+ collect:
+ type: string
+ description: collect is a script collecting results generated by simulation
+ submit_stdout:
+ type: string
+ description: submit_stdout is output generated by submit.sh (additional info in response from '/jobs/batch')
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required, token refresh required or job with provided ID does not belong to the user
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Job with provided ID does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '408':
+ description: Timeout
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ delete:
+ summary: Allows for job cancelation. Available only for jobs run on SLURM.
+ description: This endpoint can be used only by keycloak authenticated users
+ parameters:
+ - in: query
+ name: job_id
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Job was succesfully canceled
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required, token refresh required or job with provided ID does not belong to the user
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Job with provided ID does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '408':
+ description: Timeout
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# Inputs Route
+ /inputs:
+ get:
+ summary: Allows for retrieving input used to run simulation
+ parameters:
+ - in: query
+ name: job_id
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Includes input used to run simulation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ input:
+ type: object
+ properties:
+ input_json:
+ type: object
+ description: available only if simulation was run with JSON input
+ input_files:
+ type: object
+ description: files used by simulation
+ input_type:
+ type: string
+ enum: [editor, files]
+ description: simulation input type
+ number_of_all_primaries:
+ type: integer
+ description: requested number of all primaries
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required, token refresh required or job with provided ID does not belong to the user
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Job with provided ID does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# Result Routes
+ /results:
+ get:
+ summary: Allows getting results of the simulation.
+ description: If `estimator_name` is provided, the response will include results only for that specific estimator, otherwise it will return all estimators for the given job.
+ parameters:
+ - in: query
+ name: job_id
+ required: true
+ description: ID of the job to retrieve results for
+ schema:
+ type: string
+ - in: query
+ name: estimator_name
+ required: false
+ description: Name of a specific estimator to retrieve results for
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Includes results of the simulation
+ content:
+ application/json:
+ schema:
+ oneOf:
+ - type: object
+ properties:
+ message:
+ type: string
+ estimators:
+ type: array
+ items:
+ $ref: '#/components/schemas/Estimator'
+ - type: object
+ properties:
+ message:
+ type: string
+ estimator:
+ $ref: '#/components/schemas/Estimator'
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required, token refresh required or job with provided ID does not belong to the user
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Job with provided ID does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# Estimator Routes
+ /estimators:
+ get:
+ summary: Allows getting names of the estimators for the specific simulation.
+ parameters:
+ - in: query
+ name: job_id
+ required: true
+ description: ID of the job to retrieve results for
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Includes estimator names
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ estimator_names:
+ type: array
+ items:
+ type: string
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required, token refresh required or job with provided ID does not belong to the user
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Job with provided ID does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# Task Routes
+ /tasks:
+ description: Route dedicated for Backend internal communication
+ post:
+ summary: Updates task state
+ description: Used by tasks to update their state
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ simulation_id:
+ type: integer
+ description: id of task's parent simulation
+ task_id:
+ type: string
+ description: id task to update
+ update_key:
+ type: string
+ description: authentication key provided to tasks
+ update_dict:
+ type: object
+ description: dict containing update data
+ required:
+ - simulation_id
+ - task_id
+ - update_key
+ - update_dict
+ responses:
+ default:
+ description: Response JSON for all codes
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# Logfiles Routes
+ /logfiles:
+ post:
+ summary: Allows for uploading logfiles of the simulation by its tasks
+ description: At current stage of development incoming logfiles override existing ones
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ simulation_id:
+ type: integer
+ description: id of task's parent simulation
+ update_key:
+ type: string
+ description: authentication key provided to tasks
+ logfiles:
+ type: object
+ description: dict containing log files
+ required:
+ - simulation_id
+ - update_key
+ - logfiles
+ responses:
+ default:
+ description: Response JSON for all codes
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ get:
+ summary: Allows getting logfiles of the simulation
+ parameters:
+ - in: query
+ name: job_id
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Includes logfiles of the simulation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ type: string
+ logfiles:
+ type: object
+ description: dict of log files with names as keys and content as values.
+ '400':
+ description: Bad Request - Missing parameters
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '401':
+ description: Unauthorized - Invalid credentials
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '403':
+ description: Forbidden - User not found, log in required, token refresh required or job with provided ID does not belong to the user
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '404':
+ description: Job with provided ID does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+ '500':
+ description: Internal Server Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/BasicResponse'
+
+# Components
+components:
+ securitySchemes:
+ basicAuth: # <-- arbitrary name for the security scheme
+ type: http
+ scheme: basic
+ schemas:
+ BasicResponse:
+ type: object
+ properties:
+ message:
+ type: string
+ description: body message
+ KeycloakRequest:
+ type: object
+ properties:
+ username:
+ type: string
+ required:
+ - username
+ RegisterLoginRequest:
+ type: object
+ properties:
+ username:
+ type: string
+ password:
+ type: string
+ required:
+ - username
+ - password
+ Metadata:
+ type: object
+ description: static additional information
+ properties:
+ platform:
+ type: string
+ description: specifies platform on which simulation is running, can be DIRECT or BATCH
+ server:
+ type: string
+ description: specifies platform on which simulation is running, can be DIRECT or BATCH
+ input_type:
+ type: string
+ description: specifies input which was used to run simulation, can be YAPTIDE_PROJECT or INPUT_FILES
+ sim_time:
+ type: string
+ description: specifies simulator which was used to run simulation, can be SHIELDHIT or DUMMY
+ Simulation:
+ type: object
+ properties:
+ title:
+ type: string
+ description: custom title set to for this simulation
+ job_id:
+ type: string
+ description: id of the job
+ start_time:
+ type: string
+ description: starting time of the simulation
+ end_time:
+ type: string
+ description: ending time of the simulation - if it is still running the value is NULL
+ metadata:
+ $ref: '#/components/schemas/Metadata'
+ Input:
+ oneOf:
+ - type: object
+ properties:
+ input_json:
+ type: object
+ description: specifies input json
+ required:
+ - input_json
+ - type: object
+ properties:
+ input_files:
+ type: object
+ properties:
+ beam.dat:
+ type: string
+ detect.dat:
+ type: string
+ geo.dat:
+ type: string
+ mat.dat:
+ type: string
+ description: specifies input files
+ required:
+ - input_files
+ JobsRequest:
+ type: object
+ properties:
+ ntasks:
+ type: integer
+ description: specifies number of parallel tasks to be run, default is maximum available for '/jobs/direct' and 1 for '/jobs/batch'
+ sim_type:
+ type: string
+ enum: [shieldhit, dummy]
+ description: specifies simulator type
+ title:
+ type: string
+ description: custom title set to for this simulation, default is workspace
+ input_type:
+ type: string
+ enum: [editor, files]
+ description: specifies input type
+ # oneOf:
+ # - input_files:
+ # type: array
+ # items:
+ # type: object
+ # properties:
+ # beam.dat:
+ # type: string
+ # detect.dat:
+ # type: string
+ # geo.dat:
+ # type: string
+ # mat.dat:
+ # type: string
+ # description: is required if input_type is files
+ # - input_json:
+ # type: object
+ # description: input_json is required if input_type is editor
+ required:
+ - ntasks
+ - input_type
+ - sim_type
+ BatchOptions:
+ type: object
+ properties:
+ batch_options:
+ type: object
+ description: available options can be found here: https://slurm.schedmd.com/sbatch.html. NOTE: if batch_options is not provided, SLURM will run both scripts with default settings
+ properties:
+ cluster_name:
+ type: string
+ description: stands for the cluster to be used to run simulation; it has to be one of available clusters for the user - check '/user/clusters' endpoint description; if it is not provided or provided cluster name is incorrect, first available cluster will be used
+ array_options:
+ type: object
+ description: dictionary of command line options used while running files with sbatch. Pairs should be option name as key and option value as value. If 2 same parameters are specified in both options and coresponding header, parameters from header will be ignored because command line options are more important for the SLURM
+ array_header:
+ type: string
+ description: header for files run on SLURM with sbatch
+ collect_options:
+ type: object
+ description: dictionary of command line options used while running files with sbatch. Pairs should be option name as key and option value as value. If 2 same parameters are specified in both options and coresponding header, parameters from header will be ignored because command line options are more important for the SLURM
+ collect_header:
+ type: string
+ description: header for files run on SLURM with sbatch
+ JobTaskStatus:
+ type: object
+ description: error, logfiles, input_files, input_json and results are deprecated: error is now sent as message, logfiles - accessed via /logfiles endpoint, results - accessed via /results endpoint, input_files and input_json - accessed via /inputs endpoint.
+ properties:
+ task_state:
+ type: string
+ enum: [PENDING, RUNNING, COMPLETED, FAILED]
+ description: task state
+ simulated_primaries:
+ type: integer
+ description: primaries already calculated by the task
+ requested_primaries:
+ type: integer
+ description: primaries to calculate for this task
+ last_update_time:
+ type: string
+ description: last time when task was updated
+ estimated_time:
+ type: object
+ description: is returned only, when task_state is RUNNING - not always because estimation is prepared after some period of time
+ properties:
+ hours:
+ type: integer
+ minutes:
+ type: integer
+ seconds:
+ type: integer
+ JobsDirectDeleteResponse:
+ type: object
+ properties:
+ message:
+ type: string
+ merge:
+ type: object
+ properties:
+ message:
+ type: string
+ job_state:
+ type: string
+ enum: [PENDING, RUNNING, COMPLETED, FAILED]
+ tasks:
+ type: array
+ items:
+ $ref: '#/components/schemas/CanceledTaskStatus'
+ CanceledTaskStatus:
+ type: object
+ properties:
+ message:
+ type: string
+ task_state:
+ type: string
+ enum: [PENDING, RUNNING, COMPLETED, FAILED]
+ Estimator:
+ type: object
+ description: Estimator object includes estimator's name, associated metadata, and list of pages.
+ properties:
+ name:
+ type: string
+ description: The name of the estimator
+ metadata:
+ type: object
+ description: Metadata for the estimator
+ pages:
+ type: array
+ description: List of pages
+ items:
+ type: object
+ description: Page object
+ UpdateJobs:
+ type: object
+ required:
+ - sim_id
+ properties:
+ sim_id:
+ type: integer
+ description: integer, primary key of simulation in database
+ job_dir:
+ type: string
+ array_id:
+ type: integer
+ collect_id:
+ type: integer
+ task_state:
+ enum: [FAILED]
+ log:
+ type: object
+ description: dict that will be uploaded as error log to database
+security:
+ - basicAuth: [] # <-- use the same name here
diff --git a/docs/converter/tests.md b/docs/converter/tests.md
new file mode 100644
index 0000000..b8ba63c
--- /dev/null
+++ b/docs/converter/tests.md
@@ -0,0 +1,16 @@
+# Tests layout
+
+## General tests
+
+The general tests cover aspects of the converter common to all simulators.
+Currently only the Figures part of geometry is tested here.
+There is also `conftests.py` which contains fixture with location and content of a reference JSON project file.
+As for now this file is based on the SHIELD-HIT12A simualator, but could be used as well for Fluka and Topas tests.
+
+### Reference files
+
+The reference JSON file is located in `tests/shieldhit/resources/project.json` together with the expected output files.
+
+## Simulator specific tests
+
+The simulator specific tests cover aspects of the converter specific to a given simulator. They are located in the `shieldhit`, `fluka` and `topas` directories.
diff --git a/docs/frontend/examples.md b/docs/frontend/examples.md
index e73323e..5973bbd 100644
--- a/docs/frontend/examples.md
+++ b/docs/frontend/examples.md
@@ -1,6 +1,6 @@
# Examples directory
-This directory contains examples of simulation projects for the editor. To add a new example, create a new JSON file in this directory. The naming convention for the file is as follows:
+Directory public/examples in ui repository contains examples of simulation projects for the editor. To add a new example, create a new JSON file in this directory. The naming convention for the file is as follows:
- ex{number of the example}.json
diff --git a/docs/frontend/three_editor_development.md b/docs/frontend/three_editor_development.md
new file mode 100644
index 0000000..ef130ab
--- /dev/null
+++ b/docs/frontend/three_editor_development.md
@@ -0,0 +1,213 @@
+# How to implement additional commands for undo/redo functionality?
+
+### Basics
+
+After evaluating different design patterns for undo/redo we decided to use the [command-pattern](http://en.wikipedia.org/wiki/Command_pattern) for implementing undo/redo functionality in the three.js-editor.
+
+This means that every action is encapsulated in a command-object which contains all the relevant information to restore the previous state.
+
+In our implementation we store the old and the new state separately (we don't store the complete state but rather the attribute and value which has changed).
+It would also be possible to only store the difference between the old and the new state.
+
+**Before implementing your own command you should look if you can't reuse one of the already existing ones.**
+
+For numbers, strings or booleans the Set...ValueCommand-commands can be used.
+Then there are separate commands for:
+
+- setting a color property (THREE.Color)
+- setting maps (THREE.Texture)
+- setting geometries
+- setting materials
+- setting position, rotation and scale
+
+### Template for new commands
+
+Every command needs a constructor. In the constructor
+
+```javascript
+function DoSomethingCommand(editor) {
+ Command.call(this, editor); // Required: Call default constructor
+
+ this.type = 'DoSomethingCommand'; // Required: has to match the object-name!
+ this.name = 'Set/Do/Update Something'; // Required: description of the command, used in Sidebar.History
+
+ // TODO: store all the relevant information needed to
+ // restore the old and the new state
+}
+```
+
+And as part of the prototype you need to implement four functions
+
+- **execute:** which is also used for redo
+- **undo:** which reverts the changes made by 'execute'
+- **toJSON:** which serializes the command so that the undo/redo-history can be preserved across a browser refresh
+- **fromJSON:** which deserializes the command
+
+```javascript
+DoSomethingCommand.prototype = {
+ execute: function () {
+ // TODO: apply changes to 'object' to reach the new state
+ },
+
+ undo: function () {
+ // TODO: restore 'object' to old state
+ },
+
+ toJSON: function () {
+ var output = Command.prototype.toJSON.call(this); // Required: Call 'toJSON'-method of prototype 'Command'
+
+ // TODO: serialize all the necessary information as part of 'output' (JSON-format)
+ // so that it can be restored in 'fromJSON'
+
+ return output;
+ },
+
+ fromJSON: function (json) {
+ Command.prototype.fromJSON.call(this, json); // Required: Call 'fromJSON'-method of prototype 'Command'
+
+ // TODO: restore command from json
+ }
+};
+```
+
+### Executing a command
+
+To execute a command we need an instance of the main editor-object. The editor-object functions as the only entry point through which all commands have to go to be added as part of the undo/redo-history.
+On **editor** we then call **.execute(...)\*** with the new command-object which in turn calls **history.execute(...)** and adds the command to the undo-stack.
+
+```javascript
+editor.execute(new DoSomethingCommand());
+```
+
+### Updatable commands
+
+Some commands are also **updatable**. By default a command is not updatable. Making a command updatable means that you
+have to implement a fifth function 'update' as part of the prototype. In it only the 'new' state gets updated while the old one stays the same.
+
+Here as an example is the update-function of **SetColorCommand**:
+
+```javascript
+update: function ( cmd ) {
+
+ this.newValue = cmd.newValue;
+
+},
+
+```
+
+#### List of updatable commands
+
+- SetColorCommand
+- SetGeometryCommand
+- SetMaterialColorCommand
+- SetMaterialValueCommand
+- SetPositionCommand
+- SetRotationCommand
+- SetScaleCommand
+- SetValueCommand
+- SetScriptValueCommand
+
+The idea behind 'updatable commands' is that two commands of the same type which occur
+within a short period of time should be merged into one.
+**For example:** Dragging with your mouse over the x-position field in the sidebar
+leads to hundreds of minor changes to the x-position.
+The user expectation is not to undo every single change that happened while he dragged
+the mouse cursor but rather to go back to the position before he started to drag his mouse.
+
+When editing a script the changes are also merged into one undo-step.
+
+
+# Writing unit tests for undo-redo commands
+
+### Overview
+
+Writing unit tests for undo/redo commands is easy.
+The main idea to simulate a scene, execute actions and perform undo and redo.
+Following steps are required.
+
+1. Create a new unit test file
+2. Include the new command and the unit test file in the editor's test suite
+3. Write the test
+4. Execute the test
+
+Each of the listed steps will now be described in detail.
+
+### 1. Create a new unit test file
+
+Create a new file in path `test/unit/editor/TestDoSomethingCommand.js`.
+
+### 2. Include the new command in the editor test suite
+
+Navigate to the editor test suite `test/unit/unittests_editor.html` and open it.
+Within the file, go to the `` and include the new command:
+
+```html
+//
+
+//...
+
+
+// add this line
+
+//...
+```
+
+It is recommended to keep the script inclusions in alphabetical order, if possible.
+
+Next, in the same file, go to `` and include the test file for the new command:
+
+```html
+//
+
+//...
+
+
+// add this line
+
+//...
+```
+
+Again, keeping the alphabetical order is recommended.
+
+### 3. Write the test
+
+#### Template
+
+Open the unit test file `test/unit/editor/TestDoSomethingCommand.js` and paste following code:
+
+```javascript
+module('DoSomethingCommand');
+
+test('Test DoSomethingCommand (Undo and Redo)', function () {
+ var editor = new Editor();
+
+ var box = aBox('Name your box');
+
+ // other available objects from "CommonUtilities.js"
+ // var sphere = aSphere( 'Name your sphere' );
+ // var pointLight = aPointLight( 'Name your pointLight' );
+ // var perspectiveCamera = aPerspectiveCamera( 'Name your perspectiveCamera' );
+
+ // in most cases you'll need to add the object to work with
+ editor.execute(new AddObjectCommand(editor, box));
+
+ // your test begins here...
+});
+```
+
+The predefined code is just meant to ease the development, you do not have to stick with it.
+However, the test should cover at least one `editor.execute()`, one `editor.undo()` and one `editor.redo()` call.
+
+Best practice is to call `editor.execute( new DoSomethingCommand( {custom parameters} ) )` **twice**. Since you'll have to do one undo (go one step back), it is recommended to have a custom state for comparison. Try to avoid assertions `ok()` against default values.
+
+#### Assertions
+
+After performing `editor.execute()` twice, you can do your first assertion to check whether the executes are done correctly.
+
+Next, you perform `editor.undo()` and check if the last action was undone.
+
+Finally, perform `editor.redo()` and verify if the values are as expected.
+
+### 4. Execute the test
+
+Open the editor's unit test suite `test/unit/unittests_editor.html` in your browser and check the results from the test framework.
diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py
index 119b57f..1517b78 100644
--- a/docs/gen_ref_pages.py
+++ b/docs/gen_ref_pages.py
@@ -26,8 +26,3 @@
with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
nav_file.writelines(nav.build_literate_nav())
-
-# copy the openapi.yaml file from the flask_static directory to the docs directory
-flask_static_openapi_path = Path('yaptide', 'static', 'openapi.yaml')
-mkdocs_openapi_path = Path('docs', 'openapi.yaml')
-mkdocs_openapi_path.write_text(flask_static_openapi_path.read_text())
diff --git a/mkdocs.yml b/mkdocs.yml
index 4d5b10b..b2d9e39 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,9 +31,11 @@ nav:
- Examples: frontend/examples.md
- Authentication: frontend/authentication.md
- Examples: frontend/examples.md
+ - ThreeJs development: frontend/three_editor_development.md
- Converter:
- Overview: converter/index.md
- Readme: converter/readme.md
+ - Tests: converter/tests.md
- Editing documentation: documentation/index.md
plugins: