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}/details':
 119     get:
 120       tags:
 121         - Bookings
 122       summary: Get booking details
 123       description: ''
 124       operationID: bookingDetails
 125       parameters:
 126         - in: path
 127           name: bookingID
 128           required: true
 129           type: integer
 130       produces:
 131         - application/json
 132       responses:
 133         '200':
 134           description: successful operation
 135           schema:
 136             $ref: '#/definitions/Booking'
 137         '404':
 138           description: Booking does not exist
 139         '401':
 140           description: Unauthorized API key
 141   '/booking/{bookingID}/extendBooking/{days}':
 142     post:
 143       tags:
 144         - Bookings
 145       summary: Extend end date of booking
 146       description: ''
 147       operationId: extendBooking
 148       parameters:
 149         - in: path
 150           name: bookingID
 151           required: true
 152           type: integer
 153         - in: path
 154           name: days
 155           required: true
 156           type: integer
 157       responses:
 158         '200':
 159           description: successful operation
 160           schema:
 161             $ref: '#/definitions/Booking'
 162         '404':
 163           description: Booking to extend does not exist
 164         '400':
 165           description: Cannot extend Booking
 166         '401':
 167           description: Unauthorized API key
 168   '/resource_inventory/{templateLabID}/images':
 169     get:
 170       tags:
 171         - Resource Inventory
 172       summary: See valid images for a resource template
 173       description: ''
 174       operationId: viewImages
 175       parameters:
 176         - in: path
 177           name: templateLabID
 178           required: true
 179           type: integer
 180       produces:
 181         - application/json
 182       responses:
 183         '200':
 184           description: successful operation
 185           schema:
 186             $ref: '#/definitions/Image'
 187         '404':
 188           description: Resource Template does not exist
 189         '401':
 190           description: Unauthorized API key
 191   /resource_inventory/availableTemplates:
 192     get:
 193       tags:
 194         - Resource Inventory
 195       summary: All Resource Templates currently available
 196       description: ''
 197       operationId: listTemplates
 198       produces:
 199         - application/json
 200       responses:
 201         '200':
 202           description: successful operation
 203           schema:
 204             $ref: '#/definitions/ResourceTemplate'
 205         '401':
 206           description: Unauthorized API key
 207   /users:
 208     get:
 209       tags:
 210         - Users
 211       summary: See all public users that can be added to a booking
 212       description: ''
 213       operationId: getUsers
 214       produces:
 215         - application/json
 216       responses:
 217         '200':
 218           description: successful operation
 219           schema:
 220             type: array
 221             items:
 222               $ref: '#/definitions/UserProfile'
 223         '401':
 224           description: Unauthorized API key
 225   /labs:
 226     get:
 227       tags:
 228         - Lab
 229       summary: List all labs and some of their info
 230       description: ''
 231       operationId: listLabs
 232       produces:
 233         - application/json
 234       responses:
 235         '200':
 236           description: successful operation
 237           schema:
 238             type: array
 239             items:
 240               $ref: '#/definitions/Lab'
 241         '401':
 242           description: Unauthorized API Key
 243   /labs/{labID}/users:
 244     get:
 245       tags:
 246         - Lab
 247       summary: Get all users that are visible to a lab for operational purposes
 248       description: ''
 249       operationId: labUsers
 250       consumes:
 251         - application/json
 252       produces:
 253         - application/json
 254       parameters:
 255         - in: path
 256           name: labID
 257           required: true
 258           type: string
 259       responses:
 260         '200':
 261           description: successful
 262           schema: array
 263           items:
 264             $ref: '#/definitions/UserProfile'
 265         '400':
 266           description: invalid lab id
 267 securityDefinitions:
 268   AutomationAPI:
 269     type: apiKey
 270     in: header
 271     name: auth-token
 272 definitions:
 273   Lab:
 274     type: object
 275     required:
 276       - id
 277       - name
 278     properties:
 279       id:
 280         type: integer
 281         format: int64
 282       name:
 283         type: string
 284   MakeBookingTemplate:
 285     type: object
 286     required:
 287       - templateID
 288       - purpose
 289       - project
 290       - collaborators
 291       - hostname
 292       - length
 293       - imageLabID
 294     properties:
 295       templateID:
 296         type: integer
 297       purpose:
 298         type: string
 299       project:
 300         type: string
 301       collaborators:
 302         type: array
 303         items:
 304           type: string
 305           description: username of the referred user
 306       hostname:
 307         type: string
 308       length:
 309         type: integer
 310         description: length of the booking in days (max 21, min 1)
 311       imageLabID:
 312         type: integer
 313   Booking:
 314     type: object
 315     required:
 316       - id
 317       - owner
 318       - collaborators
 319       - start
 320       - end
 321       - lab
 322       - purpose
 323       - project
 324       - resourceBundle
 325     properties:
 326       id:
 327         type: integer
 328         format: int64
 329       owner:
 330         type: string
 331       collaborators:
 332         type: array
 333         items:
 334           $ref: '#/definitions/UserProfile'
 335       start:
 336         type: string
 337         format: date-time
 338       end:
 339         type: string
 340         format: date-time
 341       lab:
 342         $ref: '#/definitions/Lab'
 343       purpose:
 344         type: string
 345       resourceBundle:
 346         $ref: '#/definitions/ResourceBundle'
 347       project:
 348         type: string
 349   Image:
 350     type: object
 351     required:
 352       - labID
 353       - resources
 354     properties:
 355       labID:
 356         type: integer
 357         format: int64
 358       name:
 359         type: string
 360   ResourceBundle:
 361     type: object
 362     required:
 363       - id
 364       - resources
 365     properties:
 366       id:
 367         type: integer
 368         format: int64
 369       resources:
 370         type: array
 371         items:
 372           $ref: '#/definitions/Server'
 373   ResourceProfile:
 374     type: object
 375     required:
 376       - id
 377       - name
 378     properties:
 379       id:
 380         type: integer
 381         format: int64
 382       name:
 383         type: string
 384   UserProfile:
 385     type: object
 386     required:
 387       - id
 388       - name
 389     properties:
 390       id:
 391         type: integer
 392         format: int64
 393       name:
 394         type: string
 395   ResourceTemplate:
 396     type: object
 397     required:
 398       - id
 399       - name
 400       - resourceProfiles
 401     properties:
 402       id:
 403         type: integer
 404         format: int64
 405       name:
 406         type: string
 407       resourceProfiles:
 408         type: array
 409         items:
 410           $ref: '#/definitions/ResourceProfile'
 411   Server:
 412     type: object
 413     required:
 414       - id
 415       - labid
 416       - profile
 417     properties:
 418       id:
 419         type: integer
 420         format: int64
 421       profile:
 422         $ref: '#/definitions/ResourceProfile'
 423       labid:
 424         type: string