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: - $ref: "#/parameters/ouParam" 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: - $ref: "#/parameters/ouParam" 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: - $ref: "#/parameters/ouParam" 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" 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, picture ] security: - apikey: [] tags: - server - lab /ous/{ouid}/labs/{labid}/clients: get: description: Get all `client` objects defined in an `lab`. parameters: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" 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/status: get: description: Get execution status of all clients definied in a `lab` parameters: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" responses: "200": description: Successful response schema: type: array items: $ref: "#/definitions/StatusModel" security: - apikey: [] tags: - server - client /ous/{ouid}/labs/{labid}/clients/{clientid}: get: description: Get a `client` object. parameters: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" - $ref: "#/parameters/clientParam" 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, picture ] security: - apikey: [] tags: - server - client /ous/{ouid}/labs/{labid}/clients/{clientid}/hardware: get: description: Get the hardware definition of a `client` object. parameters: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" - $ref: "#/parameters/clientParam" 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" - $ref: "#/parameters/clientParam" 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 type: integer format: int32 minimum: 1 size: description: disk or partition size type: integer format: int64 parttable: description: partition table type (only in disk configuration) type: string enum: [ "MSDOS", "GPT", "LVM", "ZVOL" ] partition: description: partition number (only in partition configuration) type: integer format: int32 minimum: 1 parttype: description: partition type (only in partition configuration) type: string filesystem: description: filesystem type (only in partition configuration) type: string usage: description: percentage of data usage in a formated filesystem (only in partition configuration) type: integer format: int32 os: description: installed operating system (only in partition configuration) type: string image: description: restaured image data, if needed (only in partition configuration) type: object properties: id: type: integer format: int32 deploydate: description: image restauration/deploying date (only in partition configuration) type: string format: date-time updated: description: flag to check if the restaured image is updated (only in partition configuration) 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" - $ref: "#/parameters/clientParam" responses: "200": description: Successful response schema: $ref: "#/definitions/StatusModel" 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" - $ref: "#/parameters/clientParam" - 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" - $ref: "#/parameters/clientParam" - 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/labParam" - $ref: "#/parameters/clientParam" 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: - $ref: "#/parameters/ouParam" 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/repoParam" 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: - $ref: "#/parameters/ouParam" 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/imageParam" 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/imageParam" 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: - $ref: "#/parameters/ouParam" - $ref: "#/parameters/imageParam" - 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 parameters: ouParam: name: ouid in: path description: OU identificator required: true type: integer labParam: name: labid in: path description: Lab identificator required: true type: integer clientParam: name: clientid in: path description: Client identificator required: true type: integer repoParam: name: repoid in: path description: repository identificator required: true type: integer imageParam: name: imageid in: path description: image definition identificator required: true type: integer definitions: StatusModel: 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: [ "off", "ogclient", "busy", "linux", "windows", "macos", "unknown" ] loggedin: description: flag to check if an user is logged in type: boolean required: [ id, ip, status ]