aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorParker Berberian <pberberian@iol.unh.edu>2019-05-10 11:44:04 -0400
committerParker Berberian <pberberian@iol.unh.edu>2019-05-10 11:44:04 -0400
commitfb36d78022b4b6f6a7ffffb94464836026bc042c (patch)
tree2cb427c200d5d028a872be967f62e89dd5d57ebc
parent541473c28a3af6661b1971bf4d35e1da5b9a1c23 (diff)
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 <pberberian@iol.unh.edu>
-rw-r--r--open-api-spec.yaml523
1 files changed, 523 insertions, 0 deletions
diff --git a/open-api-spec.yaml b/open-api-spec.yaml
new file mode 100644
index 0000000..2e8dfd6
--- /dev/null
+++ b/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 <lab-name> 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 <lab-name> 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 <lab-name> 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 <ifname>`
+ 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