openapi.yml

openapi: 3.0.0
info:
  title: kytos/topology
  version: v3
  description: Manage the network topology.
servers:
  - url: http://localhost:8181/
    description: Local server (uses test data)
paths:
  /api/kytos/topology/v3/:
    get:
      summary: Return the latest known topology.
      description: This topology is updated when there are network events.
      responses:
        200:
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    type: array
                    items:
                      $ref: "#/components/schemas/Link"
                  switches:
                    type: array
                    items:
                      $ref: "#/components/schemas/Switch"
  /api/kytos/topology/v3/switches:
    get:
      summary: Return a json with all the switches in the topology.
      description: Return all the switches in the topology.
      responses:
        200:
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  switches:
                    type: array
                    items:
                      $ref: "#/components/schemas/Switch"
  /api/kytos/topology/v3/switches/{dpid}/enable:
    post:
      summary: Administratively enable a switch in the topology.
      description: Administratively enable a switch in the topology. The dpid
        is required.
      parameters:
        - name: dpid
          in: path
          description: Switch datapath ID
          required: true
          schema:
            type: string
          example: 00:00:00:00:00:00:00:01
      responses:
        201:
          description: Operation sucessful.
          content:
            application/json:
              schema:
                type: string
                example: Operation sucessful
        404:
          description: Switch does not exist
          content:
            application/json:
              schema:
                type: string
                example: Switch not found
  /api/kytos/topology/v3/switches/{dpid}/disable:
    post:
      summary: Administratively disable a switch in the topology.
      description: Administratively disable a switch in the topology. The dpid
        is required.
      parameters:
        - name: dpid
          schema:
            type: string
          required: true
          description: Switch datapath ID.
          in: path
          example: 00:00:00:00:00:00:00:01
      responses:
        201:
          description: Operation sucessful.
          content:
            application/json:
              schema:
                type: string
                example: Operation sucessful
        404:
          description: Switch does not exist
          content:
            application/json:
              schema:
                type: string
                example: Switch not found
  /api/kytos/topology/v3/switches/{dpid}/metadata:
    get:
      summary: Get metadata from a switch.
      description: Return a metadata from a switch. The dpid is required.
      parameters:
        - name: dpid
          schema:
            type: string
          required: true
          description: Switch datapath ID.
          in: path
          example: 00:00:00:00:00:00:00:01
      responses:
        200:
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
        404:
          description: Switch does not exist
          content:
            application/json:
              schema:
                type: string
                example: Switch not found
    post:
      summary: Add metadata to a switch.
      description: Add metadata to switch. The dpid is required.
      parameters:
        - name: dpid
          schema:
            type: string
          required: true
          description: Switch datapath ID.
          in: path
          example: 00:00:00:00:00:00:00:01
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        201:
          description: Operation sucessful
          content:
            application/json:
              schema:
                type: string
                example: Operation sucessful
        404:
          description: Switch does not exist
          content:
            application/json:
              schema:
                type: string
                example: Switch not found
  /api/kytos/topology/v3/switches/{dpid}/metadata/{key}:
    delete:
      summary: Delete metadata from a switch.
      description: Delete a metadata from a switch. The dpid and metadata key
        are required.
      parameters:
        - name: dpid
          schema:
            type: string
          required: true
          description: Switch datapath ID.
          in: path
          example: 00:00:00:00:00:00:00:01
        - name: key
          schema:
            type: string
          required: true
          description: Key of the metadata to be removed.
          in: path
      responses:
        201:
          description: Operation sucessful
          content:
            application/json:
              schema:
                type: string
                example: Operation sucessful
        404:
          description: Switch or metadata does not exist
          content:
            application/json:
              schema:
                type: string
                example: Switch not found

  /api/kytos/topology/v3/interfaces:
    get:
      summary: Return a json with all the interfaces in the topology.
      description: Return all interfaces in the topology.
      responses:
        200:
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  interfaces:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Interface'

  /api/kytos/topology/v3/interfaces/{interface_id}/enable:
    post:
      summary: Administratively enable an interface in the topology.
      description: Administratively enable an interface in the topology. The
        interface_id is required.
      parameters:
        - name: interface_id
          schema:
            type: string
          required: true
          description: The interface ID.
          in: path
      responses:
        200:
          description: Operation successful.
          content:
            application/json:
              schema:
                type: string
                example: Operation successful
        404:
          description: Switch or interface not found
          content:
            application/json:
              schema:
                type: string
                example: Switch not found

  /api/kytos/topology/v3/interfaces/switch/{dpid}/enable:
    post:
      summary: Administratively enable all interfaces on a switch.
      description: Administratively enable all interfaces on a switch.
        The dpid is required.
      parameters:
        - name: dpid
          schema:
            type: string
          required: true
          description: The switch id.
          in: path
      responses:
        200:
          description: Operation successful.
          content:
            application/json:
              schema:
                type: string
                example: Operation successful
        404:
          description: Switch or interface not found
          content:
            application/json:
              schema:
                type: string
                example: Switch not found

  /api/kytos/topology/v3/interfaces/{interface_id}/disable:
    post:
      summary: Administratively disable an interface in the topology.
      description: Administratively disable an interface in the topology.
        The interface_id is required.
      parameters:
        - name: interface_id
          schema:
            type: string
          required: true
          description: The interface ID.
          in: path
      responses:
        200:
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: string
                example: Operation successful
        404:
          description: Switch or interface not found
          content:
            application/json:
              schema:
                type: string
                example: Switch not found

  /api/kytos/topology/v3/interfaces/switch/{dpid}/disable:
    post:
      summary: Administratively disable all interfaces on a switch.
      description: Administratively disable all interfaces on a switch.
        The dpid is required.
      parameters:
        - name: dpid
          schema:
            type: string
          required: true
          description: The switch id.
          in: path
      responses:
        200:
          description: Operation successful.
          content:
            application/json:
              schema:
                type: string
                example: Operation successful
        404:
          description: Switch or interface not found
          content:
            application/json:
              schema:
                type: string
                example: Switch not found

  /api/kytos/topology/v3/interfaces/{interface_id}/metadata:
    get:
      summary: Get metadata from an interface.
      description: Return metadata from an interface. The interface_id is
        required.
      parameters:
        - name: interface_id
          schema:
            type: string
          required: true
          description: The interface ID.
          in: path
      responses:
        200:
          description: Describe a successful call.
          content:
            application/json:
              schema:
                type: object
        404:
          description: Switch or interface not found
          content:
            application/json:
              schema:
                type: string
                example: Switch not found
    post:
      summary: Add metadata to an interface.
      description: Add metada to an interface. The interface_id is required.
      parameters:
        - name: interface_id
          schema:
            type: string
          required: true
          description: The interface ID.
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        201:
          description: Operation sucessful
          content:
            application/json:
              schema:
                type: string
                example: Operation sucessful
        404:
          description: Switch or interface does not exist
          content:
            application/json:
              schema:
                type: string
                example: Switch not found
  /api/kytos/topology/v3/interfaces/{interface_id}/metadata/{key}:
    delete:
      summary: Delete metadata from an interface.
      description: Delete metadata from an interface. The interface_id and
        metadata key are required.
      parameters:
        - name: interface_id
          schema:
            type: string
          required: true
          description: The interface ID.
          in: path
        - name: key
          schema:
            type: string
          required: true
          description: Metadata key.
          in: path
      responses:
        201:
          description: Operation sucessful
          content:
            application/json:
              schema:
                type: string
                example: Operation sucessful
        404:
          description: Switch or metadata does not exist
          content:
            application/json:
              schema:
                type: string
                example: Switch not found
  /api/kytos/topology/v3/links:
    get:
      summary: Return a json with all the links in the topology.
      description: Links are connections between interfaces.
      responses:
        200:
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    type: array
                    items:
                      $ref: "#/components/schemas/Link"
  /api/kytos/topology/v3/links/{link_id}/enable:
    post:
      summary: Administratively enable a link in the topology.
      description: Administratively enable a link in the topology. The link_id
        is required.
      parameters:
        - name: link_id
          schema:
            type: string
          required: true
          description: The link ID.
          in: path
      responses:
        200:
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: string
                example: Operation successful
        404:
          description: Link not found
          content:
            application/json:
              schema:
                type: string
                example: Link not found
  /api/kytos/topology/v3/links/{link_id}/disable:
    post:
      summary: Administratively disable a link in the topology.
      description: Administratively disable a link in the topology.
        The link_id is required.
      parameters:
        - name: link_id
          schema:
            type: string
          required: true
          description: The link ID.
          in: path
      responses:
        200:
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: string
                example: Operation successful
        404:
          description: Link not found
          content:
            application/json:
              schema:
                type: string
                example: Link not found
  /api/kytos/topology/v3/links/{link_id}/metadata:
    get:
      summary: Get metadata from a link.
      description: Get metadata from a link. The link_id is required.
      parameters:
        - name: link_id
          schema:
            type: string
          required: true
          description: The link ID.
          in: path
      responses:
        200:
          description: Describe a successful call.
          content:
            application/json:
              schema:
                type: object
        404:
          description: Link not found
          content:
            application/json:
              schema:
                type: string
                example: Link not found
    post:
      summary: Add metadata to a link.
      description: Add metadata to a link. The link_id is required.
      parameters:
        - name: link_id
          schema:
            type: string
          required: true
          description: The link ID.
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        201:
          description: Operation sucessful
          content:
            application/json:
              schema:
                type: string
                example: Operation sucessful
        404:
          description: Link does not exist
          content:
            application/json:
              schema:
                type: string
                example: Link not found
  /api/kytos/topology/v3/links/{link_id}/metadata/{key}:
    delete:
      summary: Delete metadata from a link.
      description: Delete metadata from a link. The link_id and metadata key
        are required.
      parameters:
        - name: link_id
          schema:
            type: string
          required: true
          description: The link ID.
          in: path
        - name: key
          schema:
            type: string
          required: true
          description: Metadata key.
          in: path
      responses:
        201:
          description: Operation sucessful
          content:
            application/json:
              schema:
                type: string
                example: Operation sucessful
        404:
          description: Link does not exist
          content:
            application/json:
              schema:
                type: string
                example: Link not found

# Components models here
components:
  schemas:
    Switch:
      type: object
      properties:
        id:
          type: string
          description: Switch identifier.
          example: 00:00:00:00:00:00:00:01
        name:
          type: string
          description: An alternative identifier, like an alias.
          example: my-beautiful-switch
        serial:
          type: string
          description: Display the serial number of switch
        software:
           type: string
           description: Describe the software version
           example: Version 2.3.4
        ofp_version:
           type: string
           description: Openflow version
           example: '0x01'
        connection:
           type: string
           description: Address used to communicate with the controller
           example: 127.0.0.1:49330
        data_path:
           type: string
           description: Datapath identifier
        manufacturer:
           type: string
           description: Manufacture name
           example: Unkown Manufactor
        hardware:
           type: string
           description: describe the Hardware version
           example: Hardware version 2.0
        type:
          type: string
          description: Display 'switch' as device type.
          example: switch
        active:
          type: boolean
          description: The switch is active or not
          example: true
        enabled:
          type: boolean
          description: The switch is administratively enabled or not
          example: false
        dpid:
          type: string
          description: Datapath identifier
          example: 00:00:00:00:00:00:00:01
        metadata:
          type: object
          description: Switch's metadata
        interfaces:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Interface'
    Interface:
      type: object
      properties:
        id:
          type: string
          description: Interface identification
          example: 00:00:00:00:00:00:00:01:1
        link:
          type: string
          description: UUID of the link this interface is connected to
          example: 26927949-df3c-4c25-874b-3da30d8ae983
        mac:
          type: string
          description: Interface mac address
          example: 26:fb:42:20:b8:b1
        name:
          type: string
          description: interface name
          example: s1-eth1
        nni:
          type: boolean
          description: Indicates if this is a network-to-network interface
          example: false
        port_number:
          type: integer
          description: Port number on the switch
          example: 1
        speed:
          type: string
          description: The speed of this interface
          example: 10 Gbps
        switch:
          type: string
          description: The id of the switch that this interface belongs to
          example: 00:00:00:00:00:00:00:01
        type:
          type: string
          description: Indicates that this is an Interface
          enum: [interface]
          example: interface
        uni:
          type: boolean
          description: Indicates if this is a User-to-network interface
          example: true
    Link:
      type: object
      properties:
        active:
          type: boolean
          description: Link is active or not
          example: false
        enabled:
          type: boolean
          description: Link is enabled or not
          example: true
        endpoint_a:
          $ref: '#/components/schemas/Interface'
        endpoint_b:
          $ref: '#/components/schemas/Interface'