openapi.yml

openapi: 3.0.0
info:
  version: '2.3.1'
  title: Kytos Circuit Provisioning
  description: Kytos NApp for provisioning of SDN circuits.
servers:
  - url: /api/kytos/mef_eline
paths:
  /v2/evc/:
    get:
      summary: List all circuits stored.
      description: List all circuits stored.
      operationId: list_circuits
      parameters:
        - name: archived
          in: query
          schema:
            type: string
          description: "Filter for archived value, if not null. It's false by default"
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Circuit'

    post:
      summary: Creates a new circuit
      operationId: create_circuit
      requestBody:
        description: Creates a new circuit based on the endpoints and
          constraints given.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCircuit'
      responses:
        '201':
          description: EVC created. The circuit ID is being returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  circuit_id: # the unique circuit id
                    type: string
        '400':
          description: Request do not have a valid JSON or same necessary
            interface does not yet exists.
        '409':
          description: Not Acceptable. This evc already exists.
        '415':
          description: The request body mimetype is not application/json.

  /v2/evc/{circuit_id}:
    get:
      summary: Get details of a circuit
      description: Get the details of a single circuit
      operationId: get_circuit
      parameters:
        - name: circuit_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Circuit'
        '400':
          description: Circuit id not found.

    patch:
      summary: Update a circuit
      description: Update a circuit based on payload. The EVC required
        attributes (name, uni_a, uni_z) can't be updated.
      operationId: update
      parameters:
        - name: circuit_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Update a circuit based on the circuit_id and payload given
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Circuit'
      responses:
        '200':
          description: OK
        '404':
          description: Circuit id not found.
        '400':
          description: Bad request.

    delete:
      summary: Delete a circuit
      description: The flows are removed from the switches, and then the EVC is
        disabled.
      operationId: delete
      parameters:
        - name: circuit_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK

  /v2/evc/{circuit_id}/redeploy:
    patch:
      summary: Redeploy an EVC
      description: Redeploy an EVC removing and then recreating the flows.
      operationId: redeploy
      parameters:
        - name: circuit_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Accepted
        '409':
          description: Circuit disabled
  /v2/evc/{circuit_id}/metadata:
    get:
      summary: Get the metadata from en EVC
      operationId: get_metadata
      parameters:
        - name: circuit_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '404':
          description: EVC not found
    post:
      summary: Add metadata to an EVC
      operationId: add_metadata
      parameters:
        - name: circuit_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Metadata to in the form of key:value
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201': 
          description: Successful
        '400':
          description: Request problem
        '404':
          description: EVC not found
        '415':
          description: Wrong type
  /v2/evc/{circuit_id}/metadata/key:
    delete:
      summary: Remove a metadata
      operationId: delete_metadata
      parameters:
        - name: circuit_id
          in: path
          required: true
          schema:
            type: string            
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful
        '404':
          description: EVC not found
  /v2/evc/schedule/:
    get:
      summary: List all schedules stored for all circuits .
      description: List all schedules stored for all circuits .
      operationId: list_circuit_schedules
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CircuitScheduleList'

    post:
      summary: Creates a new circuit schedule
      operationId: create_schedule
      requestBody:
        description: Creates a new circuit schedule.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCircuitSchedule'
      responses:
        '201':
          description: Schedule created. The Schedule object is being returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CircuitSchedule'
        '400':
          description: Request do not have a JSON or JSON format do not match
            the Schedule object or some parameters are missing.
        '404':
          description: Circuit id not found.
        '403':
          description:  Can´t change data. Circuit is deleted and archived.
        '409':
          description: Not Acceptable.

  /v2/evc/schedule/{schedule_id}:
    patch:
      summary: Update a circuit schedule
      description: Update a circuit schedule based on payload. The schedule_id are required.
      operationId: update_schedule
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Update a circuit schedule based on the schedule_id and payload given
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CircuitSchedule'
      responses:
        '200':
          description: OK
        '400':
          description: Bad request. Invalid format or some parameters are missing.
        '403':
          description:  Can´t change data. Circuit is deleted and archived.
        '404':
          description: Schedule id not found.
    delete:
      summary: Delete a circuit schedule
      description: Delete a schedule from a circuit.
      operationId: delete_schedule
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '403':
          description:  Can´t change data. Circuit is deleted and archived.
        '404':
          description:  Schedule id not found.
components:
  #-------------------------------
  # Reusable schemas (data models)
  #-------------------------------
  schemas:
    NewCircuit: # Can be referenced via '#/components/schemas/NewCircuit'
      type: object
      required:
        - name
        - uni_a
        - uni_z
      additionalProperties: false
      properties:
        name:
          type: string
        frequency:
          type: string
        uni_a:
          $ref: '#/components/schemas/Endpoint'
        uni_z:
          $ref: '#/components/schemas/Endpoint'
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        bandwidth:
          type: integer
          format: int64
        primary_links:
          type: array
          items:
            $ref: '#/components/schemas/NewLink'
        backup_links:
          type: array
          items:
            $ref: '#/components/schemas/NewLink'
        primary_path:
          type: array
          items:
            $ref: '#/components/schemas/NewLink'
        backup_path:
          type: array
          items:
            $ref: '#/components/schemas/NewLink'
        primary_constraints:
          $ref: '#/components/schemas/PathConstraints'
        secondary_constraints:
          $ref: '#/components/schemas/PathConstraints'
        dynamic_backup_path:
          type: boolean
        circuit_scheduler:
          type: array
          items:
            $ref: '#/components/schemas/CircuitSchedule'
        sb_priority:
          type: integer
          format: int32
          description: "Southbound priority value"
          minimum: 0
        service_level:
          type: integer
          format: int32
          description: "Service level provided for network convergence. The higher the better"
          default: 0
          minimum: 0
          maximum: 7
        queue_id:
          type: integer
          format: int32
          description: "QoS Egress Queue ID"
          minimum: 0
          maximum: 7
        enabled:
          type: boolean
        metadata:
          type: object
    NewLink:
      type: object
      required:
        - endpoint_a
        - endpoint_b
      properties:
        endpoint_a:
          $ref: '#/components/schemas/NewEndpoint'
        endpoint_b:
          $ref: '#/components/schemas/NewEndpoint'
    NewEndpoint:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          minLength: 25
          maxLength: 30
          pattern: '^([0-9A-Fa-f]{2}[:-]){8}(\d{1,5})$'          
    Endpoint: # Can be referenced via '#/components/schemas/Endpoint'
      type: object
      required:
        - interface_id
      properties:
        interface_id:
          type: string
          minLength: 25
          maxLength: 30
          pattern: '^([0-9A-Fa-f]{2}[:-]){8}(\d{1,5})$'
        tag:
          $ref: '#/components/schemas/Tag'

    Link: # Can be referenced via '#/components/schemas/Link'
      type: object
      required:
        - id
        - endpoint_a
        - endpoint_b
      properties:
        id:
          type: string
        endpoint_a:
          $ref: '#/components/schemas/Endpoint'
        endpoint_b:
          $ref: '#/components/schemas/Endpoint'

    Path: # Can be referenced via '#/components/schemas/Path'
      type: object
      required:
        - endpoints
      properties:
        id:
          type: integer
          format: int32
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/Endpoint'
    PathConstraints:
      type: object
      properties:
        desired_links:
          type: array
          description: List of link IDs that should be in the path, included as a logical AND.
          items:
            type: string
          example:
            - '2bd01b0d-c875-4263-ad38-fec0b2999582'
            - 'c41f6249-3ea6-4aba-a083-08049face1e2'
        undesired_links:
          type: array
          description: List of link IDs that should not be in the path, excluded as a logical OR.
          items:
            type: string
          example:
            - "f13e8308-ecb2-49be-b507-3823af9cc409"
            - "ee8d9017-1efd-49ac-9149-4cbeea86f751"
        spf_attribute:
          type: string
          description: Link metadata attribute that will be used as link cost by SPF.
          default: "hop"
          enum: 
            - "hop"
            - "delay"
            - "priority"
        spf_max_path_cost:
          type: number
          description: Maximum accumulated path cost to be consireded. You should only set this value if you want to set an upper bound accumulated cost.
          minimum: 1
        mandatory_metrics:
          description: Constraint in the form of a set that contains attributes. Paths will have every attribute specified in this set. Links metadata must be set for the metrics to be considered.
          allOf:
            - $ref: "#/components/schemas/Attributes"
          example:
            bandwidth: 100
            ownership: "Bill"
        flexible_metrics:
          description: Constraint in the form of a set that contains attributes. Paths will have a user-specified minimum number of attributes specified in this set. Links metadata must be set for the metrics to be considered.
          allOf:
            - $ref: "#/components/schemas/Attributes"
          example:
            delay: 81
            utilization: 100
            reliability: 3
        minimum_flexible_hits:
          type: integer
          description: Minimum number of attributes listed in flexible_metrics that a path will meet.
          example: 2
          minimum: 0
          maximum: 6
    Attributes:
      type: object
      properties:
        bandwidth:
          type: number
          description: Minimum speed of the link in Gbps. It should be a positive float number.
          example: 100
          minimum: 0.1
        utilization:
          type: number
          description: Maximum average percentage of utilization of the link. Utilization as 100 means the link does not have capacity left.
          example: 70
          minimum: 0
          maximum: 100
        priority:
          type: number
          description: Maximum priority of the link. The priority of the link could be set based on certain administrative traffic-engineering criteria. 
          example: 1
          minimum: 0
        reliability:
          type: number
          description: Minimum percentage of the reliability of the link. Reliability as 0 means always down.
          example: 95
          minimum: 1
          maximum: 100
        delay:
          type: number
          description: Maximum propagation delay of the link in milliseconds. It should be a positive float number.
          example: 200
          minimum: 0.1
        ownership:
          type: string
          description: The exact user who should have ownership or be authorized to use the link.
          example: "Bill"
    Circuit: # Can be referenced via '#/components/schemas/Circuit'
      type: object
      required:
        - id
        - name
        - uni_a
        - uni_z
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        uni_a:
          $ref: '#/components/schemas/Endpoint'
        uni_z:
          $ref: '#/components/schemas/Endpoint'

        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time

        bandwidth:
          type: integer
          format: int64

        primary_links:
          type: array
          items:
            $ref: '#/components/schemas/Path'
        backup_links:
          type: array
          items:
            $ref: '#/components/schemas/Path'

        current_path:
          $ref: '#/components/schemas/Path'
        failover_path:
          $ref: '#/components/schemas/Path'
        primary_path:
          $ref: '#/components/schemas/Path'
        backup_path:
          $ref: '#/components/schemas/Path'
        primary_constraints:
          $ref: '#/components/schemas/PathConstraints'
        secondary_constraints:
          $ref: '#/components/schemas/PathConstraints'

        dynamic_backup_path:
          type: boolean
        creation_time:
          type: string
          format: date-time

        enabled:
          type: boolean

        active:
          type: boolean

        owner:
          type: string
        sb_priority:
          type: integer
          format: int32
          description: "Southbound priority value"
          minimum: 0
        service_level:
          type: integer
          format: int32
          description: "Service level provided for network convergence. The higher the better"
          default: 0
          minimum: 0
          maximum: 7
        queue_id:
          type: integer
          format: int32
          description: "QoS Egress Queue ID"
          minimum: 0
          maximum: 7

        circuit_scheduler:
          type: array
          items:
            $ref: '#/components/schemas/CircuitSchedule'
        request_time:
          type: string
          format: date-time

    Tag: # Can be referenced via '#/components/schemas/Tag'
      type: object
      required:
        - tag_type
        - value
      properties:
        tag_type:
          type: integer
          format: int32
        value:
          type: integer
          format: int32

    CircuitSchedule: # Can be referenced via '#/components/schemas/CircuitSchedule'
      type: object
      properties:
        id:
          type: integer
          format: int32
        date:
          type: string
          format: date-time
        interval:
          type: string
        frequency:
          type: string
        action:
          type: string

  #------------------------------------------
  # Reusable schemas for request or responses
  #------------------------------------------
    NewCircuitSchedule:
      type: object
      properties:
        circuit_id:
          type: integer
          format: int32
        schedule: {
            "$ref": "#/components/schemas/CircuitSchedule"
        }
    CircuitScheduleList:
      type: object
      properties:
        circuit_id:
          type: integer
          format: int32
        schedule_id:
          type: integer
          format: int32
        schedule: {
            "$ref": "#/components/schemas/CircuitSchedule"
        }