path: root/opendc-api-spec.yml

swagger: '2.0'
info:
    version: 1.0.0
    title: OpenDC API
    description: 'OpenDC is an open-source datacenter simulator for education, featuring real-time online collaboration, diverse simulation models, and detailed performance feedback statistics.'
host: opendc.org
basePath: /v2
schemes:
    - https

paths:
    '/users':
        get:
            tags:
                - users
            description: Search for a User using their email address.
            parameters:
                -   name: email
                    in: query
                    description: User's email address.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully searched Users.
                    schema:
                        $ref: '#/definitions/User'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '404':
                    description: User not found.
        post:
            tags:
                - users
            description: Add a new User.
            parameters:
                -   name: user
                    in: body
                    description: The new User.
                    required: true
                    schema:
                        $ref: '#/definitions/User'
            responses:
                '200':
                    description: Successfully added User.
                    schema:
                        $ref: '#/definitions/User'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '409':
                    description: User already exists.
    '/users/{userId}':
        get:
            tags:
                - users
            description: Get this User.
            parameters:
                -   name: userId
                    in: path
                    description: User's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully retrieved User.
                    schema:
                        $ref: '#/definitions/User'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '404':
                    description: User not found.
        put:
            tags:
                - users
            description: Update this User's given name and/ or family name.
            parameters:
                -   name: userId
                    in: path
                    description: User's ID.
                    required: true
                    type: string
                -   name: user
                    in: body
                    description: User's new properties.
                    required: true
                    schema:
                        properties:
                            givenName:
                                type: string
                            familyName:
                                type: string
            responses:
                '200':
                    description: Successfully updated User.
                    schema:
                        $ref: '#/definitions/User'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from updating User.
                '404':
                    description: User not found.
        delete:
            tags:
                - users
            description: Delete this User.
            parameters:
                -   name: userId
                    in: path
                    description: User's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully deleted User.
                    schema:
                        $ref: '#/definitions/User'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from deleting User.
                '404':
                    description: User not found.
    '/projects':
        post:
            tags:
                - projects
            description: Add a Project.
            parameters:
                -   name: project
                    in: body
                    description: The new Project.
                    required: true
                    schema:
                        properties:
                            name:
                                type: string
            responses:
                '200':
                    description: Successfully added Project.
                    schema:
                        $ref: '#/definitions/Project'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
    '/projects/{projectId}':
        get:
            tags:
                - projects
            description: Get this Project.
            parameters:
                -   name: projectId
                    in: path
                    description: Project's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully retrieved Project.
                    schema:
                        $ref: '#/definitions/Project'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from retrieving Project.
                '404':
                    description: Project not found
        put:
            tags:
                - projects
            description: Update this Project.
            parameters:
                -   name: projectId
                    in: path
                    description: Project's ID.
                    required: true
                    type: string
                -   name: project
                    in: body
                    description: Project's new properties.
                    required: true
                    schema:
                        properties:
                            project:
                                $ref: '#/definitions/Project'
            responses:
                '200':
                    description: Successfully updated Project.
                    schema:
                        $ref: '#/definitions/Project'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from updating Project.
                '404':
                    description: Project not found.
        delete:
            tags:
                - projects
            description: Delete this project.
            parameters:
                -   name: projectId
                    in: path
                    description: Project's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully deleted Project.
                    schema:
                        $ref: '#/definitions/Project'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from deleting Project.
                '404':
                    description: Project not found.
    '/projects/{projectId}/authorizations':
        get:
            tags:
                - projects
            description: Get this Project's Authorizations.
            parameters:
                -   name: projectId
                    in: path
                    description: Project's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully retrieved Project's Authorizations.
                    schema:
                        type: array
                        items:
                            type: object
                            properties:
                                userId:
                                    type: string
                                projectId:
                                    type: string
                                authorizationLevel:
                                    type: string
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from retrieving this Project's Authorizations.
                '404':
                    description: Project not found.
    '/projects/{projectId}/topologies':
        post:
            tags:
                - projects
            description: Add a Topology.
            parameters:
                -   name: projectId
                    in: path
                    description: Project's ID.
                    required: true
                    type: string
                -   name: topology
                    in: body
                    description: The new Topology.
                    required: true
                    schema:
                        properties:
                            topology:
                                $ref: '#/definitions/Topology'
            responses:
                '200':
                    description: Successfully added Topology.
                    schema:
                        $ref: '#/definitions/Topology'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
    '/projects/{projectId}/experiments':
        post:
            tags:
                - experiments
            description: Add an Experiment.
            parameters:
                -   name: projectId
                    in: path
                    description: Project's ID.
                    required: true
                    type: string
                -   name: experiment
                    in: body
                    description: The new Experiment.
                    required: true
                    schema:
                        properties:
                            topology:
                                $ref: '#/definitions/Experiment'
            responses:
                '200':
                    description: Successfully added Topology.
                    schema:
                        $ref: '#/definitions/Topology'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
    '/topologies/{topologyId}':
        get:
            tags:
                - topologies
            description: Get this Topology.
            parameters:
                -   name: topologyId
                    in: path
                    description: Topology's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully retrieved Topology.
                    schema:
                        $ref: '#/definitions/Topology'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from retrieving Topology.
                '404':
                    description: Topology not found.
        put:
            tags:
                - topologies
            description: Update this Topology's name.
            parameters:
                -   name: topologyId
                    in: path
                    description: Topology's ID.
                    required: true
                    type: string
                -   name: topology
                    in: body
                    description: Topology's new properties.
                    required: true
                    schema:
                        properties:
                            topology:
                                $ref: '#/definitions/Topology'
            responses:
                '200':
                    description: Successfully updated Topology.
                    schema:
                        $ref: '#/definitions/Topology'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from updating Topology.
                '404':
                    description: Topology not found.
        delete:
            tags:
                - topologies
            description: Delete this Topology.
            parameters:
                -   name: topologyId
                    in: path
                    description: Topology's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully deleted Topology.
                    schema:
                        $ref: '#/definitions/Topology'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from deleting Topology.
                '404':
                    description: Topology not found.
    '/experiments/{experimentId}':
        get:
            tags:
                - experiments
            description: Get this Experiment.
            parameters:
                -   name: experimentId
                    in: path
                    description: Experiment's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully retrieved Experiment.
                    schema:
                        $ref: '#/definitions/Experiment'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from retrieving Experiment.
                '404':
                    description: Experiment not found.
        put:
            tags:
                - experiments
            description: "Update this Experiment's Topology, Trace, Scheduler, and/or name."
            parameters:
                -   name: experimentId
                    in: path
                    description: Experiment's ID.
                    required: true
                    type: string
                -   name: experiment
                    in: body
                    description: Experiment's new properties.
                    required: true
                    schema:
                        properties:
                            topologyId:
                                type: string
                            traceId:
                                type: string
                            schedulerName:
                                type: string
                            name:
                                type: string
            responses:
                '200':
                    description: Successfully updated Experiment.
                    schema:
                        $ref: '#/definitions/Experiment'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from updating Experiment.
                '404':
                    description: 'Experiment, Topology, Trace, or Scheduler not found.'
        delete:
            tags:
                - experiments
            description: Delete this Experiment.
            parameters:
                -   name: experimentId
                    in: path
                    description: Experiment's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully deleted Experiment.
                    schema:
                        $ref: '#/definitions/Experiment'
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from deleting Experiment.
                '404':
                    description: Experiment not found.
    /schedulers:
        get:
            tags:
                - experiments
            description: Get all available Schedulers
            responses:
                '200':
                    description: Successfully retrieved Schedulers.
                    schema:
                        type: array
                        items:
                            $ref: '#/definitions/Scheduler'
                '401':
                    description: Unauthorized.
    /traces:
        get:
            tags:
                - experiments
            description: Get all available Traces (non-populated).
            responses:
                '200':
                    description: Successfully retrieved Traces (non-populated).
                    schema:
                        type: array
                        items:
                            type: object
                            properties:
                                _id:
                                    type: string
                                name:
                                    type: string
                '401':
                    description: Unauthorized.
    '/traces/{traceId}':
        get:
            tags:
                - experiments
            description: Get this Trace.
            parameters:
                -   name: traceId
                    in: path
                    description: Trace's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully retrieved Trace.
                    schema:
                        $ref: '#/definitions/Trace'
                '401':
                    description: Unauthorized.
                '404':
                    description: Trace not found.
    /prefabs:
        post:
            tags:
                - prefabs
            description: Add a Prefab.
            parameters:
                -   name: prefab
                    in: body
                    description: The new Prefab.
                    required: true
                    schema:
                        properties:
                            name:
                                type: string
            responses:
                '200':
                    description: Successfully added Prefab.
                    schema:
                        $ref: '#/definitions/Prefab'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
    '/prefabs/{prefabId}':
        get:
            tags:
                - prefabs
            description: Get this Prefab.
            parameters:
                -   name: prefabId
                    in: path
                    description: Prefab's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully retrieved Prefab.
                    schema:
                        $ref: '#/definitions/Prefab'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from retrieving Prefab.
                '404':
                    description: Prefab not found
        put:
            tags:
                - prefabs
            description: Update this Prefab.
            parameters:
                -   name: prefabId
                    in: path
                    description: Prefab's ID.
                    required: true
                    type: string
                -   name: prefab
                    in: body
                    description: Prefab's new properties.
                    required: true
                    schema:
                        properties:
                            project:
                                $ref: '#/definitions/Prefab'
            responses:
                '200':
                    description: Successfully updated Prefab.
                    schema:
                        $ref: '#/definitions/Prefab'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from updating Prefab.
                '404':
                    description: Prefab not found.
        delete:
            tags:
                - prefabs
            description: Delete this prefab.
            parameters:
                -   name: prefabId
                    in: path
                    description: Prefab's ID.
                    required: true
                    type: string
            responses:
                '200':
                    description: Successfully deleted Prefab.
                    schema:
                        $ref: '#/definitions/Prefab'
                '400':
                    description: Missing or incorrectly typed parameter.
                '401':
                    description: Unauthorized.
                '403':
                    description: Forbidden from deleting Prefab.
                '404':
                    description: Prefab not found.

definitions:
    Experiment:
        type: object
        properties:
            _id:
                type: string
            projectId:
                type: string
            topologyId:
                type: string
            traceId:
                type: string
            schedulerName:
                type: string
            name:
                type: string
            state:
                type: string
            lastSimulatedTick:
                type: integer
    MachineState:
        type: object
        properties:
            _id:
                type: string
            machineId:
                type: string
            experimentId:
                type: string
            tick:
                type: integer
            inUseMemoryMb:
                type: integer
            loadFraction:
                type: number
                format: float
    Prefab:
        type: object
        properties:
            _id:
                type: string
            name:
                type: string
            datetimeCreated:
                type: string
                format: dateTime
            datetimeLastEdited:
                type: string
                format: dateTime
    RackState:
        type: object
        properties:
            _id:
                type: string
            rackId:
                type: string
            experimentId:
                type: string
            tick:
                type: integer
            inUseMemoryMb:
                type: integer
            loadFraction:
                type: number
                format: float
    RoomState:
        type: object
        properties:
            _id:
                type: string
            roomId:
                type: string
            experimentId:
                type: string
            tick:
                type: integer
            inUseMemoryMb:
                type: integer
            loadFraction:
                type: number
                format: float
    Scheduler:
        type: object
        properties:
            name:
                type: string
    Project:
        type: object
        properties:
            _id:
                type: string
            name:
                type: string
            datetimeCreated:
                type: string
                format: dateTime
            datetimeLastEdited:
                type: string
                format: dateTime
            topologyIds:
                type: array
                items:
                    type: string
            experimentIds:
                type: array
                items:
                    type: string
    Topology:
        type: object
        properties:
            _id:
                type: string
            projectId:
                type: string
            name:
                type: string
            rooms:
                type: array
                items:
                    type: object
                    properties:
                        _id:
                            type: string
                        name:
                            type: string
                        tiles:
                            type: array
                            items:
                                type: object
                                properties:
                                    _id:
                                        type: string
                                    positionX:
                                        type: integer
                                    positionY:
                                        type: integer
                                    object:
                                        type: object
                                        properties:
                                            capacity:
                                                type: integer
                                            powerCapacityW:
                                                type: integer
                                            machines:
                                                type: array
                                                items:
                                                    type: object
                                                    properties:
                                                        position:
                                                            type: integer
                                                        cpuItems:
                                                            type: array
                                                            items:
                                                                type: object
                                                                properties:
                                                                    name:
                                                                        type: string
                                                                    clockRateMhz:
                                                                        type: integer
                                                                    numberOfCores:
                                                                        type: integer
                                                        gpuItems:
                                                            type: array
                                                            items:
                                                                type: object
                                                                properties:
                                                                    name:
                                                                        type: string
                                                                    clockRateMhz:
                                                                        type: integer
                                                                    numberOfCores:
                                                                        type: integer
                                                        memoryItems:
                                                            type: array
                                                            items:
                                                                type: object
                                                                properties:
                                                                    name:
                                                                        type: string
                                                                    speedMbPerS:
                                                                        type: integer
                                                                    sizeMb:
                                                                        type: integer
                                                        storageItems:
                                                            type: array
                                                            items:
                                                                type: integer
                                                                properties:
                                                                    name:
                                                                        type: string
                                                                    speedMbPerS:
                                                                        type: integer
                                                                    sizeMb:
                                                                        type: integer
    Portfolio:
        type: object
        properties:
            _id:
                type: string
            projectId:
                type: string
            name:
                type: string
            type:
                type: string
            scenarioIds:
                type: array
                items:
                    type: string
            targets:
                type: object
                properties:
                    enabledMetrics:
                        type: array
                        items:
                            type: string
                    repeatsPerScenario:
                        type: integer
    Scenario:
        type: object
        properties:
            _id:
                type: string
            portfolioId:
                type: string
            name:
                type: string
            trace:
                type: object
                properties:
                    traceId:
                        type: string
                    loadSamplingFraction:
                        type: number
            topology:
                type: object
                properties:
                    topologyId:
                        type: string
            operational:
                type: object
                properties:
                    failuresEnabled:
                        type: boolean
                    performanceInterferenceEnabled:
                        type: boolean
                    schedulerName:
                        type: string
    Trace:
        type: object
        properties:
            _id:
                type: string
            name:
                type: string
            path:
                type: string
            type:
                type: string
    User:
        type: object
        properties:
            _id:
                type: string
            googleId:
                type: integer
            email:
                type: string
            givenName:
                type: string
            familyName:
                type: string
            authorizations:
                type: array
                items:
                    type: object
                    properties:
                        projectId:
                            type: string
                        authorizationLevel:
                            type: string