laas_api_documentation.yaml

   1 swagger: '2.0'
   2 info:
   3   description: |-
   4     Details for all endpoints for LaaS automation API. This serves to allow users
   5     to create bookings outside of the web UI hosted at labs.lfnetworking.org.
   6     All included setup is referencing the development server hosted while in
   7     beta testing for the API.
   8   version: 1.0.0
   9   title: LaaS Automation API
  10   termsOfService: 'http://labs.lfnetworking.org'
  11   contact:
  12     email: opnfv@iol.unh.edu
  13   license:
  14     name: MIT License
  15 host: 10.10.30.55
  16 basePath: /api
  17 tags:
  18   - name: Bookings
  19     description: View and edit existing bookings
  20   - name: Resource Inventory
  21     description: Examine and manage resources in a lab
  22   - name: Users
  23     description: All actions for referencing
  24 schemes:
  25   - http
  26 security:
  27   - AutomationAPI: []
  28 paths:
  29   /booking:
  30     get:
  31       tags:
  32         - Bookings
  33       summary: Get all bookings belonging to user
  34       description: Get all bookings belonging to the user authenticated by API key.
  35       operationId: retrieveBookings
  36       produces:
  37         - application/json
  38       responses:
  39         '200':
  40           description: successful operation
  41           schema:
  42             type: array
  43             items:
  44               $ref: '#/definitions/Booking'
  45         '401':
  46           description: Unauthorized API key
  47   /booking/makeBooking:
  48     put:
  49       tags:
  50         - Bookings
  51       summary: Make booking by specifying information
  52       description: Exposes same functionality as quick booking form from dashboard
  53       operationId: makeBooking
  54       consumes:
  55         - application/json
  56       produces:
  57         - application/json
  58       parameters:
  59         - in: body
  60           name: booking
  61           description: the booking to create
  62           schema:
  63             $ref: '#/definitions/MakeBookingTemplate'
  64       responses:
  65         '200':
  66           description: successful operation
  67           schema:
  68             $ref: '#/definitions/Booking'
  69         '400':
  70           description: Error in booking info
  71         '401':
  72           description: Unauthorized API key
  73   '/booking/{bookingID}':
  74     get:
  75       tags:
  76         - Bookings
  77       summary: See all info for specific booking
  78       description: ''
  79       operationId: specificBooking
  80       parameters:
  81         - in: path
  82           name: bookingID
  83           required: true
  84           type: integer
  85       produces:
  86         - application/json
  87       responses:
  88         '200':
  89           description: successful operation
  90           schema:
  91             $ref: '#/definitions/Booking'
  92         '404':
  93           description: Booking does not exist
  94         '401':
  95           description: Unauthorized API key
  96     delete:
  97       tags:
  98         - Bookings
  99       summary: Cancel booking
 100       description: ''
 101       operationId: cancelBooking
 102       parameters:
 103         - in: path
 104           name: bookingID
 105           required: true
 106           type: integer
 107       produces:
 108         - application/json
 109       responses:
 110         '200':
 111           description: successfully canceled booking
 112         '404':
 113           description: Booking does not exist
 114         '400':
 115           description: Cannnot cancel booking
 116         '401':
 117           description: Unauthorized API key
 118   '/booking/{bookingID}/extendBooking/{days}':
 119     post:
 120       tags:
 121         - Bookings
 122       summary: Extend end date of booking
 123       description: ''
 124       operationId: extendBooking
 125       parameters:
 126         - in: path
 127           name: bookingID
 128           required: true
 129           type: integer
 130         - in: path
 131           name: days
 132           required: true
 133           type: integer
 134       responses:
 135         '200':
 136           description: successful operation
 137           schema:
 138             $ref: '#/definitions/Booking'
 139         '404':
 140           description: Booking to extend does not exist
 141         '400':
 142           description: Cannot extend Booking
 143         '401':
 144           description: Unauthorized API key
 145   '/resource_inventory/{templateLabID}/images':
 146     get:
 147       tags:
 148         - Resource Inventory
 149       summary: See valid images for a resource template
 150       description: ''
 151       operationId: viewImages
 152       parameters:
 153         - in: path
 154           name: templateLabID
 155           required: true
 156           type: integer
 157       produces:
 158         - application/json
 159       responses:
 160         '200':
 161           description: successful operation
 162           schema:
 163             $ref: '#/definitions/Image'
 164         '404':
 165           description: Resource Template does not exist
 166         '401':
 167           description: Unauthorized API key
 168   /resource_inventory/availableTemplates:
 169     get:
 170       tags:
 171         - Resource Inventory
 172       summary: All Resource Templates currently available
 173       description: ''
 174       operationId: listTemplates
 175       produces:
 176         - application/json
 177       responses:
 178         '200':
 179           description: successful operation
 180           schema:
 181             $ref: '#/definitions/ResourceTemplate'
 182         '401':
 183           description: Unauthorized API key
 184   /users:
 185     get:
 186       tags:
 187         - Users
 188       summary: See all public users that can be added to a booking
 189       description: ''
 190       operationId: getUsers
 191       produces:
 192         - application/json
 193       responses:
 194         '200':
 195           description: successful operation
 196           schema:
 197             type: array
 198             items:
 199               $ref: '#/definitions/UserProfile'
 200         '401':
 201           description: Unauthorized API key
 202   /labs:
 203     get:
 204       tags:
 205         - Lab
 206       summary: List all labs and some of their info
 207       description: ''
 208       operationId: listLabs
 209       produces:
 210         - application/json
 211       responses:
 212         '200':
 213           description: successful operation
 214           schema:
 215             type: array
 216             items:
 217               $ref: '#/definitions/Lab'
 218         '401':
 219           description: Unauthorized API Key
 220   /labs/{labID}/users:
 221     get:
 222       tags:
 223         - Lab
 224       summary: Get all users that are visible to a lab for operational purposes
 225       description: ''
 226       operationId: labUsers
 227       consumes:
 228         - application/json
 229       produces:
 230         - application/json
 231       parameters:
 232         - in: path
 233           name: labID
 234           required: true
 235           type: string
 236       responses:
 237         '200':
 238           description: successful
 239           schema: array
 240           items:
 241             $ref: '#/definitions/UserProfile'
 242         '400':
 243           description: invalid lab id
 244 securityDefinitions:
 245   AutomationAPI:
 246     type: apiKey
 247     in: header
 248     name: auth-token
 249 definitions:
 250   Lab:
 251     type: object
 252     required:
 253       - id
 254       - name
 255     properties:
 256       id:
 257         type: integer
 258         format: int64
 259       name:
 260         type: string
 261   MakeBookingTemplate:
 262     type: object
 263     required:
 264       - templateID
 265       - purpose
 266       - project
 267       - collaborators
 268       - hostname
 269       - length
 270       - imageLabID
 271     properties:
 272       templateID:
 273         type: integer
 274       purpose:
 275         type: string
 276       project:
 277         type: string
 278       collaborators:
 279         type: array
 280         items:
 281           type: string
 282           description: username of the referred user
 283       hostname:
 284         type: string
 285       length:
 286         type: integer
 287         description: length of the booking in days (max 21, min 1)
 288       imageLabID:
 289         type: integer
 290   Booking:
 291     type: object
 292     required:
 293       - id
 294       - owner
 295       - collaborators
 296       - start
 297       - end
 298       - lab
 299       - purpose
 300       - project
 301       - resourceBundle
 302     properties:
 303       id:
 304         type: integer
 305         format: int64
 306       owner:
 307         type: string
 308       collaborators:
 309         type: array
 310         items:
 311           $ref: '#/definitions/UserProfile'
 312       start:
 313         type: string
 314         format: date-time
 315       end:
 316         type: string
 317         format: date-time
 318       lab:
 319         $ref: '#/definitions/Lab'
 320       purpose:
 321         type: string
 322       resourceBundle:
 323         $ref: '#/definitions/ResourceBundle'
 324       project:
 325         type: string
 326   Image:
 327     type: object
 328     required:
 329       - labID
 330       - resources
 331     properties:
 332       labID:
 333         type: integer
 334         format: int64
 335       name:
 336         type: string
 337   ResourceBundle:
 338     type: object
 339     required:
 340       - id
 341       - resources
 342     properties:
 343       id:
 344         type: integer
 345         format: int64
 346       resources:
 347         type: array
 348         items:
 349           $ref: '#/definitions/Server'
 350   ResourceProfile:
 351     type: object
 352     required:
 353       - id
 354       - name
 355     properties:
 356       id:
 357         type: integer
 358         format: int64
 359       name:
 360         type: string
 361   UserProfile:
 362     type: object
 363     required:
 364       - id
 365       - name
 366     properties:
 367       id:
 368         type: integer
 369         format: int64
 370       name:
 371         type: string
 372   ResourceTemplate:
 373     type: object
 374     required:
 375       - id
 376       - name
 377       - resourceProfiles
 378     properties:
 379       id:
 380         type: integer
 381         format: int64
 382       name:
 383         type: string
 384       resourceProfiles:
 385         type: array
 386         items:
 387           $ref: '#/definitions/ResourceProfile'
 388   Server:
 389     type: object
 390     required:
 391       - id
 392       - labid
 393       - profile
 394     properties:
 395       id:
 396         type: integer
 397         format: int64
 398       profile:
 399         $ref: '#/definitions/ResourceProfile'
 400       labid:
 401         type: string