openapi: 3.1.0
info:
    title: Dojo API
    version: 3.5.0
    description: |
        **Backend API of the Dojo project.**
        
        
        See more information about the projet on
        [Gitlab](https://githepia.hesge.ch/dojo_project/dojo).
    license:
        name: AGPLv3
        identifier: AGPL-3.0-only
    contact:
        name: Michaël Minelli
        email: dojo@minelli.me
servers:
    -   url: http://localhost:30993/
        description: Development
    -   url: http://dojo-test.edu.hesge.ch/dojo/api/
        description: Test (only from HES-GE network)
    -   url: https://rdps.hesge.ch/dojo/api/
        description: Production
tags:
    -   name: General
        description: ''
    -   name: Session
        description: Routes that are used to manage the user's session
    -   name: Gitlab
        description: Routes that are used to provide Gitlab informations
    -   name: Assignment
        description: Routes that are used to manage assignments
    -   name: Exercise
        description: Routes that are used to manage exercises
paths:
    /health_check:
        get:
            tags:
                - General
            summary: Health check
            description: This route can be used to check if the server is up and running.
            responses:
                '200':
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DojoBackendResponse'
                    description: OK
                default:
                    $ref: '#/components/responses/ERROR'
    /login:
        post:
            tags:
                - Session
            summary: Login to Dojo app
            description: |
                This route can be used to connect the user to the backend and retrieve
                informations about his access rights.
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            properties:
                                accessToken:
                                    type: string
                                    format: Gitlab access token
                                refreshToken:
                                    type: string
                                    format: Gitlab refresh token
                            required:
                                - accessToken
                                - refreshToken
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                type: object
                                                nullable: true
                '404':
                    $ref: '#/components/responses/NOT_FOUND'
                default:
                    $ref: '#/components/responses/ERROR'
    /refresh_tokens:
        post:
            tags:
                - Session
            summary: Refresh tokens
            description: |
                This route can be used to refresh the session. Gitlab tokens will be
                refreshed and a new Dojo backend JWT token will be provided.
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            properties:
                                refreshToken:
                                    type: string
                                    format: Gitlab refresh token
                            required:
                                - refreshToken
            responses:
                '200':
                    description: The new Gitlab tokens as returned by Gitlab API.
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                type: object
                                                properties:
                                                    access_token:
                                                        type: string
                                                        examples:
                                                            - de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54
                                                    token_type:
                                                        type: string
                                                        examples:
                                                            - bearer
                                                    expires_in:
                                                        type: number
                                                        examples:
                                                            - 7200
                                                    refresh_token:
                                                        type: string
                                                        examples:
                                                            - 8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1
                                                    scope:
                                                        type: array
                                                        examples:
                                                            -   - api
                                                                - create_runner
                                                                - read_repository
                                                                - write_repository
                                                        items:
                                                            type: string
                                                    created_at:
                                                        type: number
                                                        examples:
                                                            - 1607635748
                                                required:
                                                    - access_token
                                                    - token_type
                                                    - expires_in
                                                    - refresh_token
                                                    - scope
                                                    - created_at
                default:
                    $ref: '#/components/responses/ERROR'
    /test_session:
        get:
            tags:
                - Session
            summary: Test of the session
            description: This route can be used to test the validity of the session token.
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DojoBackendResponse'
                default:
                    $ref: '#/components/responses/ERROR'
    /gitlab/project/{gitlabProjectIdOrNamespace}/checkTemplateAccess:
        get:
            tags:
                - Gitlab
            summary: Check access to template repository
            description: |
                This route can be used to check if the template repository is accessible by the Dojo user.
                
                **🔒 Security needs:** any access rights
            security:
                -   Clients_Token: [ ]
            parameters:
                -   $ref: '#/components/parameters/gitlabProjectIdOrNamespace'
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                type: object
                                                nullable: true
                '401':
                    $ref: '#/components/responses/UNAUTHORIZED'
                '404':
                    $ref: '#/components/responses/NOT_FOUND'
                default:
                    $ref: '#/components/responses/ERROR'
    /assignments/{assignmentNameOrUrl}:
        get:
            tags:
                - Assignment
            summary: Get an assignment
            description: |
                This route can be used to get an assignment's informations by its name or its url.
                If it's not published and the user is not a member of the staff (or admin), some informations will not be provided.
                Informations that will be deleted: 
                - gitlabId
                - gitlabLink
                - gitlabCreationInfo
                - gitlabLastInfo
                - gitlabLastInfoDate
                - staff
                - exercises
                
                **🔒 Security needs:** any access rights
            security:
                -   Clients_Token: [ ]
            parameters:
                -   $ref: '#/components/parameters/assignmentNameOrUrl'
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                $ref: '#/components/schemas/Assignment'
                '401':
                    $ref: '#/components/responses/UNAUTHORIZED'
                '404':
                    $ref: '#/components/responses/NOT_FOUND'
                default:
                    $ref: '#/components/responses/ERROR'
    /assignments:
        post:
            tags:
                - Assignment
            summary: Create a new assignment
            description: |
                **🔒 Security needs:** TeachingStaff or Admin roles
            security:
                -   Clients_Token: [ ]
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            properties:
                                name:
                                    type: string
                                    description: Name of the assignment (must be unique)
                                members:
                                    type: string
                                    format: json
                                    description: JSON string of an array of gitlab user objects
                                    externalDocs:
                                        description: Gitlab user object
                                        url: https://docs.gitlab.com/ee/api/users.html#list-users
                                template:
                                    type: string
                                    format: url
                                    description: URL of the template to use as base of the assignment
                            required:
                                - name
                                - members
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                $ref: '#/components/schemas/Assignment'
                '401':
                    $ref: '#/components/responses/UNAUTHORIZED'
                default:
                    $ref: '#/components/responses/ERROR'
    /assignments/{assignmentNameOrUrl}/publish:
        patch:
            tags:
                - Assignment
            summary: Publish an assignment
            description: |
                **🔒 Security needs:** TeachingStaff of the assignment or Admin role
            security:
                -   Clients_Token: [ ]
            parameters:
                -   $ref: '#/components/parameters/assignmentNameOrUrl'
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                type: object
                                                nullable: true
                '401':
                    $ref: '#/components/responses/UNAUTHORIZED'
                '404':
                    $ref: '#/components/responses/NOT_FOUND'
                default:
                    $ref: '#/components/responses/ERROR'
    /assignments/{assignmentNameOrUrl}/unpublish:
        patch:
            tags:
                - Assignment
            summary: Unpublish an assignment
            description: |
                **🔒 Security needs:** TeachingStaff of the assignment or Admin role
            security:
                -   Clients_Token: [ ]
            parameters:
                -   $ref: '#/components/parameters/assignmentNameOrUrl'
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                type: object
                                                nullable: true
                '401':
                    $ref: '#/components/responses/UNAUTHORIZED'
                '404':
                    $ref: '#/components/responses/NOT_FOUND'
                default:
                    $ref: '#/components/responses/ERROR'
    /assignments/{assignmentNameOrUrl}/exercises:
        post:
            tags:
                - Exercise
            summary: Create a new exercise
            description: |
                This route can be used to create a new exercise based on an assignment.
                
                **🔒 Security needs:** The assignment must be published
            security:
                -   Clients_Token: [ ]
            parameters:
                -   $ref: '#/components/parameters/assignmentNameOrUrl'
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            properties:
                                members:
                                    type: string
                                    format: json
                                    description: JSON string of an array of gitlab user objects
                                    externalDocs:
                                        description: Gitlab user object
                                        url: https://docs.gitlab.com/ee/api/users.html#list-users
                            required:
                                - members
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                $ref: '#/components/schemas/Exercise'
                '401':
                    $ref: '#/components/responses/UNAUTHORIZED'
                '404':
                    $ref: '#/components/responses/NOT_FOUND'
                '419':
                    description: |
                        At least one of the members of the exercices have reached the maximum number of exercises for this assignment.
                        
                        Users that have reached the maximum number of exercises are listed in the `data` field.
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                type: array
                                                items:
                                                    $ref: '#/components/schemas/User'
                default:
                    $ref: '#/components/responses/ERROR'
    /exercises/{exerciseId}/assignment:
        get:
            tags:
                - Exercise
                - Assignment
            summary: Get the assignment of an exercise
            security:
                -   ExerciseChecker_Secret: [ ]
            parameters:
                -   $ref: '#/components/parameters/exerciseId'
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                type: object
                                                properties:
                                                    assignment:
                                                        $ref: '#/components/schemas/Assignment'
                                                    assignmentFile:
                                                        $ref: '#/components/schemas/AssignmentFile'
                                                    immutable:
                                                        type: array
                                                        items:
                                                            type: object
                                                            description: Gitlab file object
                                                            externalDocs:
                                                                description: Gitlab file object
                                                                url: https://docs.gitlab.com/ee/api/repository_files.html#get-file-from-repository
                '401':
                    $ref: '#/components/responses/UNAUTHORIZED'
                '404':
                    $ref: '#/components/responses/NOT_FOUND'
                default:
                    $ref: '#/components/responses/ERROR'
    /exercises/{exerciseId}/results:
        post:
            tags:
                - Exercise
            summary: Get results of an exercise
            security:
                -   ExerciseChecker_Secret: [ ]
            parameters:
                -   $ref: '#/components/parameters/exerciseId'
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            properties:
                                exitCode:
                                    type: number
                                    description: The exit code of the exercise execution
                                commit:
                                    type: string
                                    format: json
                                    description: JSON string of an array of gitlab user objects
                                    externalDocs:
                                        description: Gitlab commit object
                                        url: https://docs.gitlab.com/ee/api/commits.html#get-a-single-commit
                                results:
                                    type: string
                                    format: json
                                    description: JSON string of a DojoResult object (see in schemas)
                                    externalDocs:
                                        description: DojoResult object
                                        url: '#/components/schemas/DojoResult'
                                files:
                                    type: string
                                    format: json
                                    description: JSON string of an array of file objects
                                archiveBase64:
                                    type: string
                                    format: base64
                                    description: Base64 encoded archive of the exercise's results
                            required:
                                - exitCode
                                - commit
                                - results
                                - files
                                - archiveBase64
            responses:
                '200':
                    description: OK
                    content:
                        application/json:
                            schema:
                                allOf:
                                    -   $ref: '#/components/schemas/DojoBackendResponse'
                                    -   type: object
                                        properties:
                                            data:
                                                type: object
                                                nullable: true
                '401':
                    $ref: '#/components/responses/UNAUTHORIZED'
                '404':
                    $ref: '#/components/responses/NOT_FOUND'
                default:
                    $ref: '#/components/responses/ERROR'
components:
    securitySchemes:
        Clients_Token:
            type: http
            scheme: bearer
            bearerFormat: JWT
        ExerciseChecker_Secret:
            type: apiKey
            in: header
            name: exercisesecret
    parameters:
        gitlabProjectIdOrNamespace:
            name: gitlabProjectIdOrNamespace
            description: |
                The id or the namespace of the project. The namespace is the
                path of the project (e.g. `dojo_project/dojo`).
            in: path
            required: true
            schema:
                type: string
        assignmentNameOrUrl:
            name: assignmentNameOrUrl
            description: The name or the url of an assignment.
            in: path
            required: true
            schema:
                type: string
        exerciseId:
            name: exerciseId
            description: The id of an exercise.
            in: path
            required: true
            schema:
                type: string
                format: uuidv4
    schemas:
        DojoBackendResponse:
            type: object
            properties:
                timestamp:
                    type: string
                    examples:
                        - '1992-09-30T19:00:00.000Z'
                code:
                    type: number
                    examples:
                        - 200
                description:
                    type: string
                    examples:
                        - OK
                sessionToken:
                    type: string
                    examples:
                        - JWT token (for content, see schema named 'SessionTokenJWT')
                data:
                    type: object
                    properties: { }
            required:
                - timestamp
                - code
                - description
                - sessionToken
                - data
        User:
            type: object
            properties:
                id:
                    type: number
                    examples:
                        - 142
                name:
                    type: string
                    examples:
                        - michael.minelli
                mail:
                    type: string
                    examples:
                        - dojo@minelli.me
                role:
                    type: string
                    enum:
                        - STUDENT
                        - TEACHING_STAFF
                        - ADMIN
                gitlabUsername:
                    type: string
                    examples:
                        - michael.minelli
                gitlabLastInfo:
                    type: object
                    properties: { }
                    externalDocs:
                        description: Gitlab user object
                        url: https://docs.gitlab.com/ee/api/users.html#list-users
                isTeachingStaff:
                    type: boolean
                    examples:
                        - true
                isAdmin:
                    type: boolean
                    examples:
                        - true
                deleted:
                    type: boolean
                    examples:
                        - false
                assignments:
                    type: array
                    items:
                        $ref: '#/components/schemas/Assignment'
                exercises:
                    type: array
                    items:
                        $ref: '#/components/schemas/Exercise'
            required:
                - id
                - role
                - gitlabUsername
                - isTeachingStaff
                - isAdmin
                - deleted
        Assignment:
            type: object
            properties:
                name:
                    type: string
                    examples:
                        - C_Hello_World
                gitlabId:
                    type: number
                    examples:
                        - 30992
                gitlabLink:
                    type: string
                    examples:
                        - https://githepia.hesge.ch/dojo_project
                gitlabCreationInfo:
                    type: object
                    properties: { }
                    externalDocs:
                        description: Gitlab project object
                        url: https://docs.gitlab.com/ee/api/projects.html#get-single-project
                gitlabLastInfo:
                    type: object
                    properties: { }
                    externalDocs:
                        description: Gitlab project object
                        url: https://docs.gitlab.com/ee/api/projects.html#get-single-project
                gitlabLastInfoDate:
                    type: string
                    examples:
                        - '1992-09-30 19:00:00.000'
                published:
                    type: boolean
                    examples:
                        - true
                staff:
                    type: array
                    items:
                        $ref: '#/components/schemas/User'
                exercises:
                    type: array
                    items:
                        $ref: '#/components/schemas/Exercise'
            required:
                - name
                - gitlabId
                - gitlabLink
                - gitlabCreationInfo
                - gitlabLastInfo
                - gitlabLastInfoDate
                - published
                - staff
                - exercises
        Exercise:
            type: object
            properties:
                id:
                    type: string
                    format: uuidv4
                    examples:
                        - eb5f2182-f5b1-42a9-80fc-cad384571053
                assignmentName:
                    type: string
                    examples:
                        - C_Hello_World
                name:
                    type: string
                    examples:
                        - DojoEx - C_Hello_World - michael.minelli
                gitlabId:
                    type: number
                    examples:
                        - 93092
                gitlabLink:
                    type: string
                    examples:
                        - https://githepia.hesge.ch/dojo_project/dojo
                gitlabCreationInfo:
                    type: object
                    properties: { }
                    externalDocs:
                        description: Gitlab project object
                        url: https://docs.gitlab.com/ee/api/projects.html#get-single-project
                gitlabLastInfo:
                    type: object
                    properties: { }
                    externalDocs:
                        description: Gitlab project object
                        url: https://docs.gitlab.com/ee/api/projects.html#get-single-project
                gitlabLastInfoDate:
                    type: string
                    examples:
                        - '1992-09-30 19:00:00.000'
            required:
                - id
                - assignmentName
                - name
                - gitlabId
                - gitlabLink
                - gitlabCreationInfo
                - gitlabLastInfo
                - gitlabLastInfoDate
        DojoResult:
            type: object
            properties:
                success:
                    type: boolean
                    examples:
                        - true
                containerExitCode:
                    type: number
                    examples:
                        - 0
                successfulTests:
                    type: number
                    examples:
                        - 3
                failedTests:
                    type: number
                    examples:
                        - 0
                successfulTestsList:
                    type: array
                    items:
                        type: string
                        examples:
                            - [ "Test 1", "Test 2", "Test 3" ]
                failedTestsList:
                    type: array
                    items:
                        type: string
                        examples:
                            - [ ]
            required:
                - success
                - containerExitCode
        AssignmentFile:
            type: object
            properties:
                dojoAssignmentVersion:
                    type: number
                    examples:
                        - 1
                version:
                    type: number
                    examples:
                        - 1
                immutable:
                    type: array
                    items:
                        type: object
                        properties:
                            description:
                                type: string
                                examples:
                                    - Dockerfile of the unique container
                            path:
                                type: string
                                examples:
                                    - Dockerfile
                            isDirectory:
                                type: boolean
                                examples:
                                    - false
                        required:
                            - path
                result:
                    type: object
                    properties:
                        container:
                            type: string
                            examples:
                                - hello_world
                        volume:
                            type: string
                            examples:
                                - hello_world_volume
                    required:
                        - container
            required:
                - dojoAssignmentVersion
                - version
                - immutable
                - result
        SessionTokenJWT:
            type: object
            properties:
                profile:
                    $ref: '#/components/schemas/User'
                iat:
                    type: string
                    examples:
                        - '1700749215'
            required:
                - profile
                - iat
    examples:
        DojoBackendResponseERROR:
            value:
                timestamp: '1992-09-30T19:00:00.000Z'
                code: 500
                description: ERROR_MESSAGE
                sessionToken: JWT token (for content, see schema named 'SessionTokenJWT')
                data: null
    responses:
        UNAUTHORIZED:
            description: UNAUTHORIZED
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/DojoBackendResponse'
                    example:
                        timestamp: '1992-09-30T19:00:00.000Z'
                        code: 401
                        description: UNAUTHORIZED
                        sessionToken: JWT token (for content, see schema named 'SessionTokenJWT')
                        data: null
        NOT_FOUND:
            description: NOT FOUND
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/DojoBackendResponse'
                    example:
                        timestamp: '1992-09-30T19:00:00.000Z'
                        code: 404
                        description: NOT_FOUND
                        sessionToken: JWT token (for content, see schema named 'SessionTokenJWT')
                        data: null
        ERROR:
            description: Unexpected error
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/DojoBackendResponse'
                    example:
                        timestamp: '1992-09-30T19:00:00.000Z'
                        code: 5XX or Internal code
                        description: This is an error message
                        sessionToken: JWT token (for content, see schema named 'SessionTokenJWT')
                        data: null