swagger: '2.0'

info:
  version: "1.1.0"
  title: OpenGnsys REST API definition
  description: |
    Information about the OpenGnsys REST API functions (including Server and
    Repository Manager).
  contact:
    name: OpenGnsys Project
    url: http://opengnsys.es/
  license:
    name: Creative Commons 4.0 International
    url: http://creativecommons.org/licenses/by/4.0/
basePath: /opengnsys/rest
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  apikey:
    type: apiKey
    name: Authorization
    in: header
# Paths description.
paths:
  /login:
    post:
      description: Check user login and returns his/her API key.
      parameters:
        - in: body
          name: authdata
          description: JSON authentication data
          required: true
          schema:
            type: object
            properties:
              username:
                type: string
              password:
                type: string
                format: password
      responses:
        "200":
          description: Successful login
          schema:
            type: object
            properties:
              userid:
                type: integer
                description: user identificator
                format: int32
              apikey:
                description: API key to include in ``Authorization`` header
                type: string
        "400":
          description: Missing parameters
          schema:
            type: object
            properties:
              message:
                type: string
        "500":
          description: Authentication error
          schema:
            type: object
            properties:
              message:
                type: string
      tags:
        - server
        - user
  /info:
    get:
      description: Gets OpenGnsys Server information
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              project:
                description: project name (OpenGnsys)
                type: string
              version:
                description: project version
                type: string
              release:
                description: project release
                type: string
              services:
                description: actived services
                type: array
                items:
                  type: string
                  enum: [ 'server', 'repository', 'tracker' ]
              oglive:
                description: installed ogLive clients
                type: array
                items:
                  type: object
                  properties:
                    distribution:
                      description: base distribution
                      type: string
                    kernel:
                      description: kernel version
                      type: string
                    revision:
                      description: OpenGnsys revision
                      type: string
                    directory:
                      description: installation directory
                      type: string
                    iso:
                      description: ISO file
                      type: string
            required: [ project, version, release, services ]
      tags:
        - server
        - repository 
  /status:
    get:
      description: Gets OpenGnsys Server status information
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              memInfo:
                description: memory information
                properties:
                  total:
                    description: total amount of memory
                    type: integer
                    format: int64
                  used:
                    description: amount of used memory
                    type: integer
                    format: int64
                required: [ total, used ]
              cpu:
                description: CPU information
                properties:
                  model:
                    description: processor model
                    type: string
                  usage:
                    description: average of processor load
                    type: number
                    format: float
                required: [ model, usage ]
            required: [ memInfo, cpu ]
      tags:
        - server
  /ous:
    get:
      description: Gets all `OU` objects.
      responses:
        "200":
          description: Successful response
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                  description: Organization Unit identificator
                  format: int32
                  minimum: 1
                name:
                  type: string
                  description: Organization Unit name
              required: [ id, name ]
      tags:
        - server
        - ou
  /ous/{ouid}:
    get:
      description: Get an `OU` object.
      parameters:
        - name: ouid
          in: path
          description: Organization Unit identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              id:
                type: integer
                description: OU identificator
              name:
                type: string
                description: OU name
              description:
                type: string
                description: OU description
            required: [ id, name, description ]
      security:
        - apikey: []
      tags:
        - server
        - ou
  /ous/{ouid}/groups:
    get:
      description: Get all group of labs defined in an `OU` object.
      parameters:
        - name: ouid
          in: path
          description: Organization Unit identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  description: group identificator
                  type: integer
                  format: int32
                name:
                  description: group name
                  type: string
                type:
                  description: group type
                  type: integer
                comments:
                  description: extra comments
                  type: string
                parent:
                  description: parent group
                  type: object
                  properties:
                    id:
                      description: parent group identificator
                      type: integer
                      format: int32
              required: [ id, name, comments ]
      security:
        - apikey: []
      tags:
        - server
        - ou
  /ous/{ouid}/labs:
    get:
      description: Get all `lab` objects defined in an `OU`.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                  description: laboratory identificator
                  format: int32
                name:
                  type: string
                  description: laboratory name
                inremotepc:
                  type: boolean
                  description: laboratory usable in Remote PC Project flag
                group:
                  type: object
                  properties:
                    id:
                      description: group identificator
                      type: integer
                      format: int32
                ou:
                  type: object
                  properties:
                    id:
                      description: OU identificator
                      type: integer
                      format: int32
              required: [ id, name, inremotepc, ou ]
      security:
        - apikey: []
      tags:
        - server
        - lab
  /ous/{ouid}/labs/{labid}:
    get:
      description: Get a `lab` object.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: labid
          in: path
          description: laboratory identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              id:
                description: laboratory identificator
                type: integer
                format: int32
              name:
                description: laboratory name
                type: string
              location:
                description: laboratory location 
                type: string
              description:
                description: laboratory description
                type: string
              inremotepc:
                description: check if this lab can be included in Remote PC Project
                type: boolean
              capacity:
                description: maximum number of people in the lab
                type: integer
                format: int32
              defclients:
                description: number of defined clients in the lab
                type: integer
                format: int32
              projector:
                description: check if this lab has a projector
                type: boolean
              board:
                description: check if this lab has an electronic board
                type: boolean
              routerip:
                description: lab router IP address
                type: string
              netmask:
                description: network mask to use in the lab
                type: string
              ntp:
                description: NTP server IP address
                type: string
              dns:
                description: DNS server IP address
                type: string
              proxyurl:
                description: Proxy server URL
                type: string
              mcastmode:
                description: Multicast protocol mode (full-duplex, half-duplex).
                type: string
                enum: [ "full-duplex", "half-duplex" ]
                default: "full-duplex"
              mcastip:
                description: Multicast IP address
                type: string
              mcastport:
                description: Multicast port
                type: integer
                format: int32
              mcastspeed:
                description: Multicast speed (in Mbps)
                type: integer
                format: int32
              p2pmode:
                description: Bittorrent connection type ("peer", "leecher". "seeder").
                type: string
              p2ptime:
                description: Bittorrent connection extra time (in s.)
                type: integer
                format: int32
              picture:
                description: Lab's picture file
                type: string
            required: [ id, name, location, description, inremotepc, capacity, defclients, projector, board, routerip, netmask, mcastmode, mcastip, mcastport, mcastspeed, p2pmode, p2ptime, image ]
      security:
        - apikey: []
      tags:
        - server
        - lab
  /ous/{ouid}/labs/{labid}/clients:
    get:
      description: Get all `client` objects defined in an `lab`.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: labid
          in: path
          description: Lab identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  description: client identificator
                  type: integer
                  format: int32
                name:
                  description: client name
                  type: string
                ip:
                  description: client IP address
                  type: string
                mac:
                  description: client MAC (Ethernet) address
                  type: string
                ou:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int32
                lab:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int32
              required: [ id, name, ip, mac, ou, lab ]
      security:
        - apikey: []
      tags:
        - server
        - client
  /ous/{ouid}/labs/{labid}/clients/{clientid}:
    get:
      description: Get a `client` object.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: labid
          in: path
          description: Lab identificator
          required: true
          type: integer
        - name: clientid
          in: path
          description: Client identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              id:
                description: client id
                type: integer
                format: int32
              name:
                description: client name
                type: string
              serialno:
                description: client serial number
                type: string
              netiface:
                description: main network interface
                type: string
              netdriver:
                description: client MAC address (kernel module)
                type: string
              mac:
                description: client MAC address
                type: string
              ip:
                description: client IP address
                type: string
              netmask:
                description: subnet mask address
                type: string
              routerip:
                description: network router IP address
                type: string
              repo:
                description: repository identification
                type: object
                properties:
                  id:
                    type: integer
                    format: int32
              validation:
                description: boot validation flag
                type: boolean
              boottype:
                description: boot template type
                type: string
              picture:
                description: client's picture file
                type: string
            required: [ id, name, serialno, netiface, netdriver, mac, ip, netmask, routerip, repo, validation, image ]
      security:
        - apikey: []
      tags:
        - server
        - client
  /ous/{ouid}/labs/{labid}/clients/{clientid}/hardware:
    get:
      description: Get the hardware definition of a `client` object.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: labid
          in: path
          description: Lab identificator
          required: true
          type: integer
        - name: clientid
          in: path
          description: Client identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              id:
                description: client id
                type: integer
                format: int32
              name:
                description: client name
                type: string
              hardware:
                description: hardware components
                type: array
                items:
                  type: object
                  properties:
                    type:
                      description: hardware component type
                      type: string
                    description:
                      description: hardware component description
                      type: string
                  required: [ type, description ]
            required: [ id, name, hardware ]
      security:
        - apikey: []
      tags:
        - server
        - client
  /ous/{ouid}/labs/{labid}/clients/{clientid}/diskcfg:
    get:
      description: Get disks configuration of a `client`
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: labid
          in: path
          description: Lab identificator
          required: true
          type: integer
        - name: clientid
          in: path
          description: Client identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              id:
                description: client id
                type: integer
                format: int32
              name:
                description: client name
                type: string
              diskcfg:
                description: |
                  array of disk configuration data, including general disk information and
                  partition/filesystem information (if not specified in paratmeter
                  description, it is only valid in partition configuration).
                type: array
                items:
                  type: object
                  properties:
                    disk:
                      description: disk number (only for disks configurations)
                      type: integer
                      format: int32
                    parttable:
                      description: partition table type (only for disks configurations)
                      type: string
                      enum: [ "MSDOS", "GPT", "LVM", "ZVOL" ]
                    partition:
                      description: partition number
                      type: integer
                      format: int32
                      minimum: 1
                    parttype:
                      description: partition type
                      type: string
                    size:
                      description: disk size (used in both, disk and partition configuration)
                      type: integer
                      format: int64
                    filesystem:
                      description: filesystem type
                      type: string
                    usage:
                      description: data usage percentage in a formated filesystem
                      type: integer
                      format: int32
                    os:
                      description: installed operating system
                      type: string
                    image:
                      description: restaured image data (if needed)
                      type: object
                      properties:
                        id:
                          type: integer
                          format: int32
                        deploydate:
                          description: image restauration/deploying date
                          type: string
                          format: date-time
                        updated:
                          description: flag to check if the restaured image is updated
                          type: boolean
            required: [ id, name, diskcfg ]
      security:
        - apikey: []
      tags:
        - server
        - client
  /ous/{ouid}/labs/{labid}/clients/{clientid}/status:
    get:
      description: Get execution status of a `client`
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: labid
          in: path
          description: Lab identificator
          required: true
          type: integer
        - name: clientid
          in: path
          description: Client identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              id:
                description: client id
                type: integer
                format: int32
              ip:
                description: client IP address
                type: string
              status:
                description: execution status
                type: string
                enum: [ "nodata", "off", "ogclient", "busy", "linux", "windows", "unknown" ]
              loggedin:
                description: flag to check if an user is logged in
                type: boolean
            required: [ id, ip, status, loggedin ]
      security:
        - apikey: []
      tags:
        - server
        - client
  /ous/{ouid}/labs/{labid}/clients/{clientid}/events:
    post:
      description: Store UDS server URLs to resend some events recieved from OGAgent.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: labid
          in: path
          description: Lab identificator
          required: true
          type: integer
        - name: clientid
          in: path
          description: Client identificator
          required: true
          type: integer
        - name: data
          in: body
          description: Operation data
          required: true
          schema:
            type: object
            properties:
              urlLogin:
                description: URL to resend a login event.
                type: string
              urlLogout:
                description: URL to resend a logout event.
                type: string
            required: [ urlLogin, urlLogout ]
      responses:
        "200":
          description: Successful response
        "400":
          description: Error message
          schema:
            type: object
            properties:
              message:
                type: string
      security:
        - apikey: []
      tags:
        - server
        - client
        - remotepc
  /ous/{ouid}/labs/{labid}/clients/{clientid}/session:
    post:
      description: Record session data for a client.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: labid
          in: path
          description: Lab identificator
          required: true
          type: integer
        - name: clientid
          in: path
          description: Client identificator
          required: true
          type: integer
        - name: data
          in: body
          description: Session parameters
          required: true
          schema:
            type: object
            properties:
              logoutAt:
                description: Time to send a logout operation to the client
                type: string
                format: date-time
      responses:
        "200":
          description: Successful response
      security:
        - apikey: []
      tags:
        - server
        - client
        - remotepc
  /ous/{ouid}/labs/{labid}/clients/{clientid}/unreserve:
    delete:
      description: Unreserve a client, clear its session data and send a poweroff operation.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: labid
          in: path
          description: Lab identificator
          required: true
          type: integer
        - name: clientid
          in: path
          description: Client identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
      security:
        - apikey: []
      tags:
        - server
        - client
        - remotepc
  /ous/{ouid}/repos:
    get:
      description: Get all `repo` objects defined in an `OU`.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                  format: int32
                name:
                  type: string
                ou:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int32
              required: [ id, name, ou ]
      security:
        - apikey: []
      tags:
        - server
        - repo
  /ous/{ouid}/repos/{repoid}:
    get:
      description: Get a `repo` object.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: repoid
          in: path
          description: repository identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              id:
                description: repository id
                type: integer
                format: int32
              name:
                description: repository name
                type: string
              description:
                description: repository description
                type: string
              ip:
                description: repository IP address
                type: string
            required: [ id, name, description, ip ]
      security:
        - apikey: []
      tags:
        - server
        - repo
  /ous/{ouid}/images:
    get:
      description: Get all `image` objects defined in an `OU`.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                  format: int32
                name:
                  type: string
                inremotepc:
                  type: boolean
                ou:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int32
              required: [ id, name, inremotepc, ou ]
      security:
        - apikey: []
      tags:
        - server
        - image
  /ous/{ouid}/images/{imageid}:
    get:
      description: Get an `image` object.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: imageid
          in: path
          description: image definition identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              id:
                description: image id
                type: integer
                format: int32
              name:
                description: image name
                type: string
              description:
                description: image description
                type: string
              comments:
                description: extra comments
                type: string
              inremotepc:
                description: image usable in Remote PC Project flag
                type: boolean
              repo:
                description: repository identification
                type: object
                properties:
                  id:
                    type: integer
                    format: int32
              type:
                description: image type (``monolithic``, ``basic``, ``incremental``)
                type: string
              baseimg:
                description: base image for an incremental image (if ``type`` is ``incremental``)
                type: string
              client:
                description: model client's data
                type: object
                properties:
                  id:
                    description: model client's id.
                    type: integer
                    format: int32
                  disk:
                    description: source disk number
                    type: integer
                    format: int32
                  partition:
                    description: source partition number
                    type: integer
                    format: int32
                required: [ id, disk, partition ]
              creationdate:
                description: image creation date
                type: string
                format: date-time
              release:
                description: image creation release
                type: string
            required: [ id, name, description, comments, inremotepc, repo, type ]
      security:
        - apikey: []
      tags:
        - server
        - image
  /ous/{ouid}/images/{imageid}/software:
    get:
      description: Get software inventory store into an `image`
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: imageid
          in: path
          description: image definition identificator
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              id:
                description: image id
                type: integer
                format: int32
              name:
                description: image name
                type: string
              software:
                description: software installed
                type: object
                properties:
                  os:
                    description: operating system
                    type: string
                  applications:
                    type: array
                    items:
                      description: list of applications (name and version)
                      type: string
            required: [ id, name, software ]
      security:
        - apikey: []
      tags:
        - server
        - image
  /ous/{ouid}/images/{imageid}/reserve:
    post:
      description: |
        Reserve a random client with an installed image and send a boot/reboot operation.
        If `labid` is specified, then choose a `client` defined in this lab.
      parameters:
        - name: ouid
          in: path
          description: OU identificator
          required: true
          type: integer
        - name: imageid
          in: path
          description: image definition identificator
          required: true
          type: integer
        - name: labid
          in: query
          description: lab. identificator
          required: false
          type: integer
      responses:
        "200":
          description: Reserve a client to boot using an operating system image.
          schema:
            type: object
            properties:
              id:
                description: selected client id
                type: integer
                format: int32
              mac:
                description: client MAC address
                type: string
              ip:
                description: client IP address
                type: string
              lab:
                description: client's lab
                type: object
                properties:
                  id:
                    description: lab id
                    type: integer
                    format: int32
                required: [ id ]
              ou:
                description: client's OU
                type: object
                properties:
                  id:
                    description: OU id
                    type: integer
                    format: int32
                required: [ id ]
            required: [ id, mac, ip, lab, ou ]
      security:
        - apikey: []
      tags:
        - server
        - image
        - remotepc
  /repository/images:
    get:
      description: Get information about images stored in a repository
      responses:
        "200":
          description: Successful response
          schema:
            type: object
            properties:
              disk:
                description: repository disk information
                type: object
                properties:
                  total:
                    description: total disk space
                    type: string
                  used:
                    description: disk space used by files
                    type: string
                  free:
                    description: amount of free disk space
                    type: string
                  percent:
                    description: percentage of used space
                    type: string
                required: [ total, used, free, percent ]
              images:
                description: information about stored images
                type: object
                properties:
                  file:
                    description: image file information
                    type: object
                    properties:
                      name:
                        description: file name
                        type: string
                      size:
                        description: file size (bytes)
                        type: integer
                        format: int64
                      modified:
                        description: file modification date
                        type: string
                        format: date-time
                      permissions:
                        description: file permissions
                        type: string
                    required: [ name, size, modified, permissions ]
            required: [ disk, images ]
      security:
        - apikey: []
      tags:
        - repository
        - image
  #/repository/poweron
  /ogagent/started:
    post:
      description: Process push notification when OGAgent is started
      parameters:
        - in: body
          name: data
          description: Operation data
          required: true
          schema:
            type: object
            properties:
              ip:
                type: string
              mac:
                type: string
              ostype:
                type: string
              osversion:
                type: string
              secret:
                type: string
      responses:
        "200":
          description: Successful operation
        "400":
          description: An error has occurred
      tags:
        - server
        - agent
  /ogagent/stopped:
    post:
      description: Process push notification when OGAgent is stopped
      parameters:
        - in: body
          name: data
          description: Operation data
          required: true
          schema:
            type: object
            properties:
              ip:
                type: string
              mac:
                type: string
              ostype:
                type: string
              osversion:
                type: string
      responses:
        "200":
          description: Successful operation
        "400":
          description: An error has occurred
      tags:
        - server
        - agent
  /ogagent/loggedin:
    post:
      description: Process push notification when an user logged in
      parameters:
        - in: body
          name: data
          description: Operation data
          required: true
          schema:
            type: object
            properties:
              ip:
                type: string
              user:
                type: string
      responses:
        "200":
          description: Successful operation
        "400":
          description: An error has occurred
      tags:
        - server
        - agent
  /ogagent/loggedout:
    post:
      description: Process push notification when an user is logged in
      parameters:
        - in: body
          name: data
          description: Operation data
          required: true
          schema:
            type: object
            properties:
              ip:
                type: string
              user:
                type: string
      responses:
        "200":
          description: Successful operation
        "400":
          description: An error has occurred
      tags:
        - server
        - agent
