swagger: '2.0'
info:
  title: Firecracker Actions Network Interfaces API
  description: RESTful public-facing API. The API is accessible through HTTP calls on specific URLs carrying JSON modeled data. The transport medium is a Unix Domain Socket.
  version: 1.16.0-dev
  termsOfService: ''
  contact:
    email: firecracker-maintainers@amazon.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
host: localhost
basePath: /
schemes:
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: Network Interfaces
paths:
  /network-interfaces/{iface_id}:
    put:
      summary: Creates a network interface. Pre-boot only.
      description: Creates new network interface with ID specified by iface_id path parameter.
      operationId: putGuestNetworkInterfaceByID
      parameters:
      - name: iface_id
        in: path
        description: The id of the guest network interface
        required: true
        type: string
      - name: body
        in: body
        description: Guest network interface properties
        required: true
        schema:
          $ref: '#/definitions/NetworkInterface'
      responses:
        204:
          description: Network interface created/updated
        400:
          description: Network interface cannot be created due to bad input
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Internal server error
          schema:
            $ref: '#/definitions/Error'
      tags:
      - Network Interfaces
    patch:
      summary: Updates the rate limiters applied to a network interface. Post-boot only.
      description: Updates the rate limiters applied to a network interface.
      operationId: patchGuestNetworkInterfaceByID
      parameters:
      - name: iface_id
        in: path
        description: The id of the guest network interface
        required: true
        type: string
      - name: body
        in: body
        description: A subset of the guest network interface properties
        required: true
        schema:
          $ref: '#/definitions/PartialNetworkInterface'
      responses:
        204:
          description: Network interface updated
        400:
          description: Network interface cannot be updated due to bad input
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Internal server error
          schema:
            $ref: '#/definitions/Error'
      tags:
      - Network Interfaces
definitions:
  NetworkInterface:
    type: object
    description: Defines a network interface.
    required:
    - host_dev_name
    - iface_id
    properties:
      guest_mac:
        type: string
      host_dev_name:
        type: string
        description: Host level path for the guest network interface
      iface_id:
        type: string
      rx_rate_limiter:
        $ref: '#/definitions/RateLimiter'
      tx_rate_limiter:
        $ref: '#/definitions/RateLimiter'
  PartialNetworkInterface:
    type: object
    description: Defines a partial network interface structure, used to update the rate limiters for that interface, after microvm start.
    required:
    - iface_id
    properties:
      iface_id:
        type: string
      rx_rate_limiter:
        $ref: '#/definitions/RateLimiter'
      tx_rate_limiter:
        $ref: '#/definitions/RateLimiter'
  RateLimiter:
    type: object
    description: Defines an IO rate limiter with independent bytes/s and ops/s limits. Limits are defined by configuring each of the _bandwidth_ and _ops_ token buckets. This field is optional for virtio-block config and should be omitted for vhost-user-block configuration.
    properties:
      bandwidth:
        $ref: '#/definitions/TokenBucket'
        description: Token bucket with bytes as tokens
      ops:
        $ref: '#/definitions/TokenBucket'
        description: Token bucket with operations as tokens
  TokenBucket:
    type: object
    description: Defines a token bucket with a maximum capacity (size), an initial burst size (one_time_burst) and an interval for refilling purposes (refill_time). The refill-rate is derived from size and refill_time, and it is the constant rate at which the tokens replenish. The refill process only starts happening after the initial burst budget is consumed. Consumption from the token bucket is unbounded in speed which allows for bursts bound in size by the amount of tokens available. Once the token bucket is empty, consumption speed is bound by the refill_rate.
    required:
    - refill_time
    - size
    properties:
      one_time_burst:
        type: integer
        format: int64
        description: The initial size of a token bucket.
        minimum: 0
      refill_time:
        type: integer
        format: int64
        description: The amount of milliseconds it takes for the bucket to refill.
        minimum: 0
      size:
        type: integer
        format: int64
        description: The total number of tokens this bucket can hold.
        minimum: 0
  Error:
    type: object
    properties:
      fault_message:
        type: string
        description: A description of the error condition
        readOnly: true