---
swagger: '2.0'
info:
  version: 1.0.0
  title: Borderline server API
  description: |
    #### Rest API for the borderline project
schemes:
  - http
host: 127.0.0.1:3000
basePath: /
paths:
    /login:
        post:
            tags: [ auth, session ]
            description: Initialize a new authenticated session
            parameters:
                -
                    name: credentials
                    required: true
                    in: body
                    schema:
                        type: object
                        properties:
                            username:
                                type: string
                                description: Username part of the credentials
                            password:
                                type: string
                                description: Password part of the credentials
            responses:
                200:
                    description: Authentication success
                401:
                    description: Authentication failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /logout:
        post:
            tags: [ auth, session ]
            description: Terminates the current session
            responses:
                401:
                    description: Failed session end
                    schema:
                        $ref: '#/definitions/ErrorModel'

                500:
                    description: Internal session management error
                    schema:
                        $ref: '#/definitions/ErrorModel'
                200:
                    description: Successful session end
    /whoami:
        get:
            tags: [ session ]
            description: Get the user from the current session
            responses:
                200:
                    description: Session has a user
                    schema:
                        $ref: '#/definitions/UserModel'
                401:
                    description: Session doesn't have a user
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /2step/login:
        post:
            tags: [ auth, session ]
            description: Create a session using two step authentication
            parameters:
                -
                    name: credentials
                    required: true
                    in: body
                    schema:
                        type: object
                        properties:
                            username:
                                type: string
                                description: Username part of the credentials
                            password:
                                type: string
                                description: Password part of the credentials
                            token:
                                type: string
                                description: 30 seconds valid two step token
            responses:
                200:
                    description: Sucessful authentication
                401:
                    description: Authentication failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /2step/{user_id}:
        put:
            tags: [ auth, session ]
            description: Regenerate user two factor secret key
            parameters:
                -
                    name: user_id
                    required: true
                    in: path
                    type: string
                    description: Target user id to regenerate for
            responses:
                200:
                    description: Successful generation
                    schema:
                        type: string
                403:
                    description: Generation failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /users:
        get:
            tags: [ user ]
            description: List all the users. Requires admin privileges
            responses:
                200:
                    description: Listing successful
                    schema:
                        type: array
                        items:
                            $ref: '#/definitions/UserModel'
                401:
                    description: Fails to list users
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /users/{user_id}:
        parameters:
            -
                name: user_id
                required: true
                type: string
                in: path
                description: User identifier
        get:
            tags: [ user ]
            description: Get a specific user

            responses:
                200:
                    description: Found this user
                    schema:
                        $ref: '#/definitions/UserModel'
                404:
                    description: User is unknown
                    schema:
                        $ref: '#/definitions/ErrorModel'
        post:
            tags: [ user ]
            description: Update a specific user
            responses:
                200:
                    description: Update user success
                    schema:
                        $ref: '#/definitions/UserModel'
                default:
                    description: Update user failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
        delete:
            tags: [ user ]
            description: Delete a specific user
            responses:
                200:
                    description: User has been deleted
                default:
                    description: Failed to delete user
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /extension_store:
        get:
            tags: [ extension ]
            description: List all the extensions
            responses:
                200:
                    description: Successful listing
                    schema:
                        type: array
                        items:
                            $ref: '#/definitions/ExtensionModel'
    /extension_store/{extension_id}:
        parameters:
            -
                name: extension_id
                required: true
                description: Id of the extension
                in: path
                type: string
        get:
            tags: [ extension ]
            description: Get an extension
            responses:
                200:
                    description: Success, replies extension information
                    schema:
                        $ref: '#/definitions/ExtensionModel'
                default:
                    description: Cannot retreive extension information
                    schema:
                        $ref: '#/definitions/ErrorModel'
        post:
            tags: [ extension ]
            description: Update extension content
            responses:
                200:
                    description: Successfuly updated extension
                    schema:
                        $ref: '#/definitions/ExtensionModel'
                default:
                    description: Failed to update extension
                    schema:
                        $ref: '#/definitions/ErrorModel'
                406:
                    description: Missing extension files
                    schema:
                        $ref: '#/definitions/ErrorModel'
        delete:
            tags: [ extension ]
            description: Removes extension from server
            responses:
                200:
                    description: Success, extension is removed
                401:
                    description: Failure, no extension has been removed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /users/{user_id}/extensions:
        parameters:
            -
                name: user_id
                required: true
                type: string
                in: path
                description: User identifier for this query
        get:
            tags: [ user, extension ]
            description: List this user Extension
            responses:
                200:
                    description: Success, returns list of extensions
                    schema:
                        type: array
                        items:
                            $ref: '#/definitions/ExtensionModel'
                default:
                    description: Failure, cannot list this user extensions
                    schema:
                        $ref: '#/definitions/ErrorModel'
        delete:
            tags: [ user, extension ]
            description: Removes all user extensions
            responses:
                200:
                    description: User no longer uses extensions
                default:
                    description: Operation failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /users/{user_id}/extensions/{extension_id}:
        parameters:
            -
                name: user_id
                required: true
                type: string
                in: path
                description: User identifier for this query
            -
                name: extension_id
                required: true
                type: string
                in: path
                description: Extension target, using identifier
        put:
            tags: [ user, extension ]
            description: Enable extension for this user
            responses:
                200:
                    description: Successfuly enabled extension
                401:
                    description: Enabling the extension failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
        delete:
            tags: [ user, extension ]
            description: Disable extension for this user
            responses:
                200:
                    description: Successfuly disabled extension
                401:
                    description: Disabling the extension failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /data_sources:
        get:
            tags: [ data source ]
            description: List all known data sources
            responses:
                200:
                    description: Successful listing
                    schema:
                        type: array
                        items:
                            $ref: '#/definitions/DataSourceModel'
                default:
                    description: Listing failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
        post:
            tags: [ data source ]
            description: Create a new data source
            responses:
                200:
                    description: Created a new data source
                    schema:
                        $ref: '#/definitions/DataSourceModel'
                default:
                    description: Something went wrong during creation
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /data_sources/{source_id}:
        parameters:
            -
                name: source_id
                required: true
                type: string
                in: path
                description: Identifier for the targeted data source
        get:
            tags: [ data source ]
            description: Get a single data source information
            responses:
                200:
                    description: Successful data source retreival
                    schema:
                        $ref: '#/definitions/DataSourceModel'
                default:
                    description: Failed to retreive this data source
                    schema:
                        $ref: '#/definitions/ErrorModel'
        post:
            tags: [ data source ]
            description: Update a single data source
            responses:
                200:
                    description: Update sucessfull
                    schema:
                        $ref: '#/definitions/DataSourceModel'
                default:
                    description: Update failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
        delete:
            tags: [ data source ]
            description: Forget a single data source
            responses:
                200:
                    description: Data source has been removed
                default:
                    description: No deletion has occured
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /users/{user_id}/data_sources/{source_id}:
        parameters:
            -
                name: user_id
                required: true
                type: string
                in: path
                description: User identifier to manipulate
            -
                name: source_id
                required: true
                type: string
                in: path
                description: Source identifier to use
        post:
            tags: [ user, data source ]
            description: Subscribe a user to a specific data source
            responses:
                200:
                    description: User has been subscribed
                default:
                    description: Failed to subscribe to data source
                    schema:
                        $ref: '#/definitions/ErrorModel'
        delete:
            tags: [ user, data source ]
            description: Unsubscribe user from a specific data source
            responses:
                200:
                    description: Unsubsribe success
                default:
                    description: Unsubscribe operation failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /workflow/:
        put:
            tags: [ workflow ]
            description: Creates a new workflow
            parameters:
                -
                    name: New workflow
                    required: true
                    in: body
                    schema:
                        type: object
                        properties:
                            name:
                                description: "Name of the new workflow"
                                type: string
            responses:
                200:
                    description: Creation success
                    schema:
                        $ref: '#/definitions/WorkflowModel'
                401:
                    description: Creation failure
                    schema:
                        $ref: '#/definitions/ErrorModel'
        get:
            tags: [ workflow ]
            description: List all the workflows
            responses:
                200:
                    description: Listing successful
                    schema:
                        type: array
                        items:
                            $ref: '#/definitions/WorkflowModel'
                401:
                    description: Listing failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /workflow/{workflow_id}:
        parameters:
            -
                name: workflow_id
                required: true
                in: path
                type: string
                description: Target workflow unique identifier
        get:
            tags: [ workflow ]
            description: Get a workflow from it's unique identifier
            responses:
                200:
                    description: Found the queried worflow
                    schema:
                        $ref: '#/definitions/WorkflowModel'
                default:
                    description: Getting from unique identifier failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
        post:
            tags: [ workflow ]
            description: Update a workflow from its unique identifier
            responses:
                200:
                    description: Update sucessful
                    schema:
                        $ref: '#/definitions/WorkflowModel'
                default:
                    description: Update failed, nothing has been modified
                    schema:
                        $ref: '#/definitions/ErrorModel'
        delete:
            tags: [ workflow ]
            description: Delete a workflow fcrom it's unique identifier
            responses:
                200:
                    description: Delete successful
                default:
                    description: Operation failed, nothing removed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /workflow/{workflow_id}/step:
        parameters:
            -
                name: workflow_id
                required: true
                type: string
                description: Target workflow unique identifier
                in: path
        get:
            tags: [ workflow, step ]
            description: List this workflow steps
            responses:
                200:
                    description: Listing success
                    schema:
                        $ref: '#/definitions/StepModel'
                default:
                    description: Error occured while listing
                    schema:
                        $ref: '#/definitions/ErrorModel'
        put:
            tags: [ workflow, step ]
            description: Create a new step in this workflow
            parameters:
                -
                    name: step
                    description: Step creation data
                    in: body
                    schema:
                        type: object
                        properties:
                            parent:
                                type: string
                                description: Parent step unique identifier, null for root step
                            extension:
                                type: string
                                description: Extension used during this new Step
                            action:
                                type: string
                                description: Action registered by the Extension
                            data:
                                type: object
                                description: Context data from the extension
            responses:
                200:
                    description: Creation success
                    schema:
                        $ref: '#/definitions/StepModel'
                default:
                    description: Opreration failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
    /workflow/{workflow_id}/step/{step_id}:
        parameters:
            -
                name: workflow_id
                required: true
                type: string
                description: Target workflow unique identifier
                in: path
            -
                name: step_id
                required: true
                type: string
                description: Target step unique identifier
                in: path
        get:
            tags: [ workflow,  step ]
            description: Get a step from it's unique identifier in a specific workflow
            responses:
                200:
                    description: Step found, success
                    schema:
                        $ref: '#/definitions/StepModel'
                default:
                    description: Operation failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
                404:
                    description: No matching id operation failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
        post:
            tags: [ workflow, step ]
            description: Update a step in this workflow, by unique identifier
            responses:
                200:
                    description: Step update success
                    schema:
                        $ref: '#/definitions/StepModel'
                default:
                    description: Step update failed, nothing changed
                    schema:
                        $ref: '#/definitions/ErrorModel'
        delete:
            tags: [ workflow, step ]
            description: Removes a specific step form a workflow
            responses:
                200:
                    description: Delete operation success
                default:
                    description: Delete opration failed
                    schema:
                        $ref: '#/definitions/ErrorModel'
definitions:
    ErrorModel:
        type: object
        properties:
            error:
                type: string
                description: A more detailed error message
    UserModel:
        type: object
        properties:
            _id:
                type: string
                description: User unique identifier
            username:
                type: string
            password:
                type: string
                description: Password hash
            admin:
                type: boolean
                description: Administrator privileges flag
    DataSourceModel:
        type: object
        properties:
            sourceType:
                type: string
                description: Type of the underlying endpoint. Transmart, I2B2, ...
            sourceName:
                type: string
                description: Display name
            sourceHost:
                type: string
                description: URL or IP where the source is hosted
            sourcePort:
                type: integer
                description: Port used by this endpoint
            public:
                type: boolean
                description: Publicly available, without auth endpoint
            users:
                type: array
                items:
                    type: string
                    description: User unique ID
                description: Array of users subscribed to this source
    ExtensionModel:
        type: object
        properties:
            _id:
                type: string
                description: Extension unique identifier
            enabled:
                type: boolean
                description: Is this extension active on the server
            name:
                type: string
                description: Display name
            description:
                type: string
                description: Display description
            author:
                type: string
                description: Display authors
            build:
                type: string
                description: Unique build hash
            version:
                type: string
                description: Extension version
    StepModel:
        type: object
        properties:
            _id:
                type: string
                description: Step unique identifier
            create:
                type: string
                format: dateTime
                description: String containing the date and time of creation
            update:
                type: string
                format: dateTime
                description: String containing the date and time of the last update
            workflow:
                type: string
                description: Workflow unique identifier this step belongs to
            user:
                type: string
                description: Unique identifier of the creator
            extension:
                type: string
                description: Extension ID used in this step
            action:
                type: string
                description: Action sent by the plugin in this step
            context:
                type: object
                description: JSON object representing the context props of the state
    WorkflowStepModel:
        type: object
        description: Workflow step description
        properties:
            id:
                type: string
                description: Step unique identifier
            parent:
                type: string
                description: Step unique identifier from which this step is derived
            children:
                type: array
                description: List of steps unique identifiers derived from this step. Recursive type WorkflowStepModel
                items:
                    type: object
    WorkflowModel:
        type: object
        properties:
            _id:
                type: string
                description: Workflow unique identifier
            name:
                type: string
                description: Display name of the workflow
            create:
                type: string
                format: dateTime
                description: String containing the date and time of creation
            update:
                type: string
                format: dateTime
                description: Date and time of the last edit
            owner:
                type: string
                description: User owning the workflow by unique identifier
            read:
                type: array
                description: Users with read access on this workflow
                items:
                    type: string
                    description: User unique identifier
            write:
                type: array
                description: Users with write access on this workflow
                items:
                    type: string
                    description: User unique identifer
            graph:
                $ref: '#/definitions/WorkflowStepModel'