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
        - name: metadata
          in: query
          schema:
            oneOf:
              - type: string
              - type: integer
              - type: boolean
          description: Filter for metadata values with format metadata.key=value, e.g. "metadata.required=false"
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                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
                  deployed:
                    type: boolean
        '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 (creation_time, active, current_path,
        failover_path, _id, archived) 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/UpdateCircuit'
      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
        - name: try_avoid_same_s_vlan
          description: Avoid tags from currently deployed current_path.
          in: query
          schema:
            type: boolean
          required: false
      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.

  /v2/evc/metadata:
    post:
      summary: Add metadata to a bulk of EVCs
      description: Add metadata to multiple EVCs based on the body content
      operationId: bulk_add_metadata
      requestBody:
        description: Metadata to be added to the EVCs
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - circuit_ids
              properties:
                circuit_ids:
                  type: array
                  minItems: 1
                  items:
                    type: string
            
      responses:
        '200':
          description: Operation successful
        '400':
          description: The request body is not a well-formed JSON or circuit_ids is missing
        '404':
          description: There were EVCs not found.
          content:
            aplication/json:
              schema:
                type: array
                items:
                  type: string
        '415':
          description: The request body mimetype is not application/json

  /v2/evc/metadata/{key}:
    delete:
      summary: Delete metadata to a bulk of EVCs
      description: Delete metadata from multiple EVCs based on the given key
      operationId: bulk_delete_metadata
      requestBody:
        description: Metadata to be deleted from the EVCs
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - circuit_ids
              properties:
                circuit_ids:
                  type: array
                  items:
                    type: string
      parameters:            
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Operation successful
        '400':
          description: The request body is not a well-formed JSON or circuit_ids is missing
        '404':
          description: There were EVCs not found.
          content:
            aplication/json:
              schema:
                type: array
                items:
                  type: string
        '415':
          description: The request body mimetype is not application/json

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/Link'
        backup_links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        primary_path:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        backup_path:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        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
          nullable: true
          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
          nullable: true
          format: int32
          description: "QoS Egress Queue ID. Value -1 can be use to set this field to default."
          minimum: -1
          maximum: 7
        enabled:
          type: boolean
        metadata:
          type: object
    NewLink: # Can be referenced via '#/components/schemas/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:
        - endpoint_a
        - endpoint_b
      properties:
        id:
          type: string
        endpoint_a:
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
        endpoint_b:
          type: object
          additionalProperties: false
          properties:
            id:
              type: string

    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:
        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. If it's not set, the default value will be settings.SPF_ATTRIBUTE, which defaults to "hop"
          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"
        not_ownership:
          type: array
          items:
            type: string
          description: The list of users whose links should not be used.
          example: ["Ted"]
    Circuit: # Can be referenced via '#/components/schemas/Circuit'
      type: object
      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/Link'
        backup_links:
          type: array
          items:
            $ref: '#/components/schemas/Link'

        current_path:
          type: array
          items:
            $ref: '#/components/schemas/NewLink'
        failover_path:
          type: array
          items:
            $ref: '#/components/schemas/NewLink'
        primary_path:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        backup_path:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        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
          nullable: true
          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
          nullable: true
          description: "QoS Egress Queue ID. Value -1 can be use to set this field to default."
          minimum: -1
          maximum: 7

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

    UpdateCircuit: # Can be referenced via '#/components/schemas/UpdateCircuit'
      type: object
      additionalProperties: false
      properties:
        uni_a:
          $ref: '#/components/schemas/Endpoint'
        uni_z:
          $ref: '#/components/schemas/Endpoint'
        name:
          type: string
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
        queue_id:
          type: integer
          format: int32
          nullable: true
          description: "QoS Egress Queue ID. Value -1 can be use to set this field to default."
          minimum: -1
          maximum: 7
        bandwidth:
          type: integer
          format: int64
        primary_path:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        backup_path:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        primary_links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        backup_links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        dynamic_backup_path:
          type: boolean
        primary_constraints:
          $ref: '#/components/schemas/PathConstraints'
        secondary_constraints:
          $ref: '#/components/schemas/PathConstraints'
        owner:
          type: string
        sb_priority:
          type: integer
          format: int32
          nullable: true
          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
        circuit_scheduler:
          type: array
          items:
            $ref: '#/components/schemas/CircuitSchedule'
        metadata:
          type: object
        enabled:
          type: boolean

    Tag: # Can be referenced via '#/components/schemas/Tag'
      type: object
      properties:
        tag_type:
          oneOf:
          - type: string
          - type: integer
          enum: ['vlan', 1]
        value:
          oneOf:
            - type: integer
              format: int32
            - type: string
            - type: array
              minItems: 1
              items:
                anyOf:
                  - type: array
                    minItems: 1
                    items:
                      anyOf:
                        - type: integer
                  - type: integer
          example: [[1, 500], 2096, [3001]]

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

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