openapi.yml

openapi: 3.0.0
info:
  title: kytos/pathfinder
  version: v2
  description: "**Warning**: *This documentation is experimental and will
  change soon.*\n

  Keeps track of topology changes, and calculates the best path between two
  points."

paths:
  /api/kytos/pathfinder/v2:
    post:
      summary: "Return a list of best paths between source and destination, in order."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  type: string
                  description:
                  required: true
                  example: '00:00:00:00:00:00:00:01:1'
                destination:
                  type: string
                  description: "The destination identifier. It may be a datapath or an interface."
                  required: true
                  example: '00:00:00:00:00:00:00:02:2'
                desired_links:
                  type: array
                  required: false
                  description: "List of desired links inside all paths found. All paths will have the desired links."
                  example:
                    - "f13e8308-ecb2-49be-b507-3823af9cc409"
                    - "ee8d9017-1efd-49ac-9149-4cbeea86f751"
                    - "a3723e31-bdd3-4102-8b1a-c9fbde6d301a"
                undesired_links:
                  type: array
                  required: false
                  description: "List of undesired links in all paths found. When an undesired link is found the endpoint will ignore remove that."
                  example:
                    - '2bd01b0d-c875-4263-ad38-fec0b2999582'
                    - 'c41f6249-3ea6-4aba-a083-08049face1e2'
                    - '7e8b6bd2-701e-4465-894a-40623e727047'
                parameter:
                  type: array
                  required: false
                  description:  "Optional parameters sent to pathfinder"
                  example: "custom_weight"
      responses:
        200:
          description: "Best paths calculated with success."
          content:
            application/json:
              schema:
                type: object
                properties:
                  paths:
                    type: array
                    items:
                      $ref: "#/components/schemas/Path"

components:
  schemas:
    Hop:
      type: string
      description: Hop identification. Usally is a `switch.id:interface.id`.
      example: 00:00:00:00:00:00:00:01:1

    Path:
      type: object
      description: Path between two points
      properties:
        hops:
          type: array
          description: Hops between two points
          items:
            $ref: "#/components/schemas/Hop"
          example:
            $ref: "#/examples/Hops"

examples:
  Hops:
    - 00:00:00:00:00:00:00:01:1
    - 00:00:00:00:00:00:00:01
    - 00:00:00:00:00:00:00:01:2
    - 00:00:00:00:00:00:00:02:1
    - 00:00:00:00:00:00:00:02
    - 00:00:00:00:00:00:00:02:2