From bea2c72168b590c972e9c4a5eaa552dc6a25707e Mon Sep 17 00:00:00 2001 From: Parker Berberian Date: Fri, 10 May 2019 11:44:04 -0400 Subject: Adds API Spec Adds the Open API Spec in YAML format to the git repo so we can track changes alongside the code Change-Id: Id23e5480a25d5e5b71e467c56ad78d1f34010999 Signed-off-by: Parker Berberian --- dashboard/open-api-spec.yaml | 523 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 523 insertions(+) create mode 100644 dashboard/open-api-spec.yaml (limited to 'dashboard') diff --git a/dashboard/open-api-spec.yaml b/dashboard/open-api-spec.yaml new file mode 100644 index 0000000..2e8dfd6 --- /dev/null +++ b/dashboard/open-api-spec.yaml @@ -0,0 +1,523 @@ +--- +swagger: "2.0" +info: + description: This is the Lab as a Service API + version: 2.0.1 + title: LaaS API + contact: + email: nfvlab@iol.unh.edu + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html +host: virtserver.swaggerhub.com +basePath: /IOL-OPNFV-LaaS/Labs/1.0.0 +tags: +- name: admin + description: Secured Admin-only calls +- name: developers + description: Operations available to regular developers +schemes: +- https +paths: + /api/labs/{lab-name}/jobs/new: + get: + summary: list of new, unstarted jobs for the lab + description: | + List of jobs for to start. These jobs all must have a status of `new`, + meaning they are unstarted. + produces: + - application/json + parameters: + - name: lab-name + in: path + required: true + type: string + responses: + 200: + description: search results matching criteria + schema: + type: array + items: + $ref: '#/definitions/Job' + /api/labs/{lab-name}/jobs/current: + get: + summary: list of unfinished jobs + description: | + List of jobs for that are still in progress. A job is in progress if + it has been started but has not finished. + produces: + - application/json + parameters: + - name: lab-name + in: path + required: true + type: string + responses: + 200: + description: search results matching criteria + schema: + type: array + items: + $ref: '#/definitions/Job' + /api/labs/{lab-name}/jobs/done: + get: + summary: list of done jobs + description: | + List of jobs for that were started and are no longer in progress. + A job can be marked 'done' with a succesful or error status. + produces: + - application/json + parameters: + - name: lab-name + in: path + required: true + type: string + responses: + 200: + description: search results matching criteria + schema: + type: array + items: + $ref: '#/definitions/Job' + /api/labs/{lab-name}/jobs/{job_id}/{task_id}>: + post: + summary: update job information + produces: + - application/json + parameters: + - name: lab-name + in: path + required: true + type: string + - name: job_id + in: path + required: true + type: integer + - name: task_id + in: path + required: true + type: string + - in: body + name: payload + description: payload, schema based on job type + required: true + schema: + $ref: '#/definitions/JobUpdate' + responses: + 200: + description: success + /api/labs/{lab-name}/inventory: + get: + summary: lab inventory + produces: + - application/json + parameters: + - name: lab-name + in: path + required: true + type: string + responses: + 200: + description: lab inventory + schema: + $ref: '#/definitions/Inventory' + post: + summary: updates lab inventory + parameters: + - name: lab-name + in: path + required: true + type: string + - in: body + name: inventory + required: true + schema: + $ref: '#/definitions/Inventory' + responses: + 200: + description: success + /api/labs/{lab-name}/profile: + get: + summary: lab profile + produces: + - application/json + parameters: + - name: lab-name + in: path + required: true + type: string + responses: + 200: + description: lab profile + schema: + $ref: '#/definitions/Profile' + post: + summary: updates lab profile + parameters: + - name: lab-name + in: path + required: true + type: string + - in: body + name: profile + required: true + schema: + $ref: '#/definitions/Profile' + responses: + 200: + description: success +definitions: + Host_Interface: + properties: + mac: + type: string + example: 00:11:22:33:44:55 + description: mac address + busaddr: + type: string + example: 0000:02:00.1 + description: bus address reported by `ethtool -i ` + switchport: + $ref: '#/definitions/Switchport' + Generic_Interface: + properties: + speed: + type: string + example: 10G + description: speed in M or G + name: + type: string + example: eno3 + description: interface name + Generic_Disk: + properties: + size: + type: string + example: 500G + description: size in M, G, or T + type: + type: string + example: SSD + description: must be SSD or HDD + name: + type: string + example: sda + description: name of root block device + CPU: + properties: + cores: + type: integer + format: int32 + example: 64 + description: how many CPU cores the host has (across all physical cpus) + minimum: 1 + arch: + type: string + example: x86_64 + description: must be x86_64 or aarch64 + cpus: + type: integer + example: 2 + description: Number of different physical CPU chips + minimum: 1 + Image: + properties: + name: + type: string + description: + type: string + lab_id: + type: string + description: identifier provided by lab + dashboard_id: + type: string + description: identifier provided by dashboard + Inventory_Host: + properties: + interfaces: + type: array + items: + $ref: '#/definitions/Host_Interface' + hostname: + type: string + example: hpe3.opnfv.iol.unh.edu + description: globally unique fqdn + host_type: + type: string + description: name of host type this host belongs to + Inventory_Network: + properties: + cidr: + type: string + example: 174.0.5.0/24 + description: subnet description + gateway: + type: string + example: 174.0.5.1 + description: ip of gateway + vlan: + type: integer + example: 100 + description: vlan tag of this network + Inventory: + properties: + hosts: + type: array + description: all hosts + items: + $ref: '#/definitions/Inventory_Host' + networks: + type: array + description: all networks + items: + $ref: '#/definitions/Inventory_Network' + images: + type: array + description: available images + items: + $ref: '#/definitions/Image' + host_types: + type: array + description: all host types hosted by a lab + items: + $ref: '#/definitions/Host_Type' + Host_Type: + properties: + cpu: + $ref: '#/definitions/CPU' + disks: + type: array + items: + $ref: '#/definitions/Generic_Disk' + description: + type: string + description: human readable description of host type + interface: + type: array + items: + $ref: '#/definitions/Generic_Interface' + ram: + $ref: '#/definitions/Ram' + name: + type: string + description: lab-unique name + Ram: + properties: + amount: + type: integer + example: 16 + description: amount of ram in Gibibytes (GiB) + Switchport: + properties: + switch_name: + type: string + example: Cisco-9 + description: name of switch owning this switchport + port_name: + type: string + example: Ethernet1/34 + description: name of port on switch + invariant_config: + type: array + description: list of vlans that may not be modified on this port + items: + $ref: '#/definitions/Vlan' + current_config: + type: array + description: list of current vlan configuration + items: + $ref: '#/definitions/Vlan' + Vlan: + properties: + vlan_id: + type: integer + example: 100 + description: vlan id + minimum: 1 + maximum: 4098 + tagged: + type: boolean + example: true + description: whether this vlan is tagged or untagged + Job: + properties: + id: + type: integer + description: globally unique job identifier + payload: + $ref: '#/definitions/JobPayload' + JobPayload: + properties: + hardware: + $ref: '#/definitions/HardwareTask' + software: + $ref: '#/definitions/SoftwareTask' + network: + $ref: '#/definitions/NetworkTask' + access: + $ref: '#/definitions/AccessTask' + snapshot: + $ref: '#/definitions/SnapshotTask' + HardwareTask: + properties: + taskId: + $ref: '#/definitions/HardwareConfig' + SoftwareTask: + properties: + taskId: + $ref: '#/definitions/SoftwarePayload' + NetworkTask: + properties: + taskId: + $ref: '#/definitions/NetworkPayload' + AccessTask: + properties: + taskId: + $ref: '#/definitions/AccessPayload' + SnapshotTask: + properties: + taskId: + $ref: '#/definitions/SnapshotPayload' + SnapshotPayload: + properties: + host: + type: string + example: hpe3 + description: how the lab identifies the host + image: + type: string + example: "4" + description: lab id of existing image, if updating an existing image. if this key does not exist, the lab must create a new image + dashboard_id: + type: string + description: how the dashboard identifies this image / snapshot + AccessPayload: + properties: + revoke: + type: boolean + description: whether to revoke key during completion of job + user: + type: string + description: PK/ID of user access is being given to + access_type: + type: string + example: ssh + description: type of access key to be generated. Options include "vpn and ssh" + hosts: + type: array + description: hosts to grant access to if applicable + items: + type: string + description: id of host + lab_token: + type: string + description: identifier provided by lab to this task + HardwareConfig: + properties: + id: + type: string + description: ID of host + image: + type: integer + example: 42 + description: lab provided ID of the request image + power: + type: string + example: on + description: desired power state, either on or off + hostname: + type: string + example: my_new_machine + description: user-defined hostname + ipmi_create: + type: boolean + description: whether or not to create an ipmi account + lab_token: + type: string + description: identifier provided by lab to this task + SoftwarePayload: + properties: + opnfv: + $ref: '#/definitions/OpnfvConfiguration' + lab_token: + type: string + description: identifier provided by lab to this task + OpnfvHost: + properties: + hostname: + type: string + example: Jumphost + description: maps hostname to OPNFV role + OpnfvConfiguration: + properties: + installer: + type: string + description: Installer user wants + scenario: + type: string + description: scenario of OPNFV to deploy + pdf: + type: string + example: LaaS.com/api/my_job/pdf + description: URL to find the Pod Descriptor File contents + idf: + type: string + example: LaaS.com/api/my_job/idf + description: URL to find the Installer Descriptor File contents + roles: + type: array + description: role the host will play in OPNFV + items: + $ref: '#/definitions/OpnfvHost' + NetworkPayload: + properties: + hostId: + $ref: '#/definitions/NetworkConfig' + lab_token: + type: string + description: identifier provided by lab to this task + NetworkConfig: + properties: + interface_name: + type: array + description: list of vlans on this interface + items: + $ref: '#/definitions/Vlan' + JobUpdate: + properties: + status: + type: integer + description: status type, see status enum + message: + type: string + description: message from lab for user + lab_token: + type: string + description: identifier provided by lab to this task + Profile: + properties: + name: + type: string + description: proper expanded lab name + contact: + $ref: '#/definitions/Contact' + description: + type: string + host_count: + type: array + items: + $ref: '#/definitions/Host_Number' + Host_Number: + properties: + type: + type: string + count: + type: integer + Contact: + properties: + phone: + type: string + description: phone number at which a lab can be reached + email: + type: string + description: email at which a lab can be reached -- cgit 1.2.3-korg