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
        "500":
          description: Authentication error
      tags:
        - server
        - user
  /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
      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
      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
                ou:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: OU identificator
                      format: int32
      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
              image:
                description: Lab's picture file
                type: string
      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:
                  type: integer
                  format: int32
                name:
                  type: string
                ou:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int32
                lab:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int32
      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
              image:
                description: client's picture file
                type: string
      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
      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
      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
      tags:
        - server
        - client
  /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
      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
      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
      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
              inremotepc:
                description: image usable in Remote PC Project flag
                type: boolean
              type:
                description: image type (``monolithic``, ``basic``, ``incremental``)
                type: string
              baseimg:
                description: base image for an incremental image (if ``type`` is ``incremental``)
                type: string
              path:
                description: image path (if ``type`` is ``incremental``)
                type: string
              repo:
                description: repository identification
                type: object
                properties:
                  id:
                    type: integer
                    format: int32
              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
              creationdate:
                description: image creation date
                type: string
                format: date-time
              release:
                description: image creation release
                type: string
      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
              os:
                description: installed operating system
                type: string
              software:
                description: array of installed applications
                type: array
                items:
                  type: object
                  properties:
                    application:
                      description: application name and version
                      type: string
      security:
        - apikey: []
      tags:
        - server
        - image
  #/ous/{ouid}/images/{imageid}/boot:
  #/repository/images
  #/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

