aa.yaml

swagger: '2.0'
info:
  version: '0.0.1'
  title: ONEM API
  description: |
    ONEM Network Manager is a plugin-based framework aiming on configuration
    of abstractly defined networks.
    ## Configuration
    Configuration is handled via 3 configuration tables.
    ### System Configuration
    ONEM is able to collect configuration state from system. This config is
    reported by `/system/config` and is in the same format as configuration
    requested by user.
    ### Running Configuration
    When `/running/config` is changes, ONEM tries to apply give configuration
    in the system. If all steps succeeds it finally compares requested
    configuration with actual system configuration returned by `system/config`.
    If configurations matches, requested configuration is saved as
    persistent.
    If configurations differs (or configuration failed), ONEM tries to
    rollback by modifying differing values. It configurations differs after
    this step, ONEM tries to set up empty configuration (plugins must handle
    this special conrner case of absolute removal differently to standard
    setup) and setup original config. If even now the configuration differs,
    ONEM stops itself (sets empty configuration and revives original network
    configuration).
    ### Persistent Configuration
    Configuration set in `/persistent/config` is copied to `/running/config`
    upon ONEM service restart. You can persist running configuration by
    copying it into persistent table and vice-versa.
    ## Additional State Information
    Some information (for example IP address obtained from DHCP server) is not
    a part of configuration. Such information is reported by `/system/state`.
    ## Plugins
    ONEM does not handle any configuration on its own, it delegates it to
    plugins instead. Plugins extend API with their schemes and add callback
    scripts for configuration and reporting. TODO move to plugins devel docs
    Each scripts must handle rollback of partial configuration on its own.
    Everything cofigured must be also reportable via `/system/config`. For
    additional info read ONEMs plugin development documentation.
    ## Service
    All system changes are removed when ONEM service stops. Thanks to that,
    troubleshooting without actual API access is as simple as service restart.
    ## Controll
    ONEM is running as a uWSGI REST-based service on an unix socket. If you
    want to use it remotely, you can attach nginx server to that.
    For localhost usage you can use `onemctl` binary which allows regular users
    to read configuration and root to change it.
    # Plugins Documentation
    ## Base
    ## IPv4
    ## Connectivity Check

tags:
  - name: persistentconf
    description: Persistent Configuration
  - name: runningconf
    description: Running Configuration
  - name: systemconf
    description: System Configuration
  - name: systemstate
    description: System State
basePath: /v0
paths:
  /persistent/config:
    get:
      tags:
        - persistentconf
      summary: Read persistent configuration database
      responses:
        200:
          description: Success
          schema:
            $ref: '#/definitions/Config'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      tags:
        - persistentconf
      summary: Update persistent configuration database
      description: >
        Stored configuration will be uploaded to `/running/config` upon ONEM
        service restart.
      parameters:
        - name: config
          in: body
          required: true
          schema:
            $ref: '#/definitions/Config'
      responses:
        200:
          description: Success
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /running/config:
    get:
      tags:
        - runningconf
      summary: Read running configuration database
      responses:
        200:
          description: Success
          schema:
            $ref: '#/definitions/Config'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      tags:
        - runningconf
      summary: Update running configuration database and configure system with it
      parameters:
        - name: config
          in: body
          required: true
          schema:
            $ref: '#/definitions/Config'
        - name: X-Connectivity-Check-Method
          in: header
          type: string
          enum:
            - 'disabled'
            - 'ping'
          default: 'disabled'
        - name: X-Connectivity-Check-Ping-Destination
          in: header
          type: string
          pattern: '^(?:[a-zA-Z0-9\-]+\.)*[a-zA-Z0-9]+$'
        - name: X-Connectivity-Check-Ping-Timeout
          in: header
          type: integer
          minimum: 0
          maximum: 3600
          default: 10
      responses:
        200:
          description: Success
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /system/config:
    get:
      tags:
        - systemconf
      summary: Read configuration build from actual system state
      responses:
        200:
          description: Success
          schema:
            $ref: '#/definitions/Config'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /system/state:
    get:
      tags:
        - systemstate
      summary: Read various information about system state
      description: >
        This includes data that are non-directly requested by configuration
        database, for example IP address obtained from DHCP server or
        name of implicitly created Open vSwitch bridge.
      responses:
        200:
          description: Success
          schema:
            $ref: '#/definitions/State'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  Config:
    type: object
    properties:
      networks:
        $ref: '#/definitions/ConfigNetworks'
  ConfigNetworks:
    type: array
    items:
      $ref: '#/definitions/ConfigNetwork'
  ConfigNetwork:
    type: object
    required:
      - name
    properties:
      name:
        type: string
      southbound:
        type: string
      ipv4:
        $ref: '#/definitions/ConfigIPv4'
  ConfigIPv4:
    type: object
    description: >
      Blablablasdbaljdh 
      asfdsfsa
      safdasdf
    properties:
      method:
        type: string
        enum:
          - 'auto'
          - 'link-local'
          - 'manual'
          - 'disabled'
        default: 'disabled'
      addresses:
        type: array
        items:
          type: object
          properties:
            address:
              $ref: '#/definitions/IPv4Address'
            prefix:
              $ref: '#/definitions/IPv4Prefix'
      gateway:
        $ref: '#/definitions/IPv4Address'
      routes:
        type: array
        items:
          $ref: '#/definitions/IPv4Route'
      dns:
        type: array
        items:
          $ref: '#/definitions/IPv4Address'
  State:
    type: object
    properties:
      networks:
        $ref: '#/definitions/StateNetworks'
  StateNetworks:
    type: array
    items:
      $ref: '#/definitions/StateNetwork'
  StateNetwork:
    type: object
    properties:
      name:
        type: string
      bridge:
        type: string
      ipv4:
        $ref: '#/definitions/StateIPv4'
  StateIPv4:
    type: object
    properties:
      addresses:
        type: array
        items:
          type: object
          properties:
            address:
              $ref: '#/definitions/IPv4Address'
            prefix:
              $ref: '#/definitions/IPv4Prefix'
      gateway:
        $ref: '#/definitions/IPv4Address'
      routes:
        type: array
        items:
          $ref: '#/definitions/IPv4Route'
      dns:
        type: array
        items:
          $ref: '#/definitions/IPv4Address'
  IPv4Route:
    type: object
    properties:
      destination: 
        $ref: '#/definitions/IPv4Address'
      prefix: 
        $ref: '#/definitions/IPv4Prefix'
      gateway:
        $ref: '#/definitions/IPv4Address'
      metric:
        type: integer
        format: int64
  IPv4Address:
    type: string
    pattern: '^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$'
  IPv4Prefix:
    type: integer
    minimum: 0
    maximum: 32
  Error:
    type: object
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string