openapi: 3.1.0
info:
  title: 'Forward Networks: Network Topology API'
  summary: List the links inferred between network devices and override them if necessary
  description: "A network’s topology influences the behavior of the network model and how automatic network layout works in the\napplication. The\_Forward Platform determines what device links to include in its network model using 1) automatic\ndiscovery using collected LLDP/CDP information, 2) automatic inference based on the MAC addresses devices have\nlearned, and 3) any user-defined link overrides, which have the highest precedence.\n\nThe resources in this section are for listing all of a network’s device links and for listing and defining\n_link overrides_. An\_override is bidirectional and either `present` (the link exists) or `absent` (the link\ndoesn’t exist)."
  contact:
    email: support@forwardnetworks.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  version: ${apiVersion}
servers:
  - url: /api
security:
  - api_token: []
tags:
  - name: Network Topology
    description: List the links inferred between network devices and override them if necessary
paths:
  /snapshots/{snapshotId}/topology:
    get:
      tags:
        - Network Topology
      summary: Get the network topology
      description: The links in the response are directed, so they generally appear twice—once for each direction.
      operationId: getTopology
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopologyLink'
        '409':
          description: |-
            The system is currently processing this Snapshot.

            Note: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the
            latest Snapshot is done or to identify an alternate Snapshot that has already been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
  /snapshots/{snapshotId}/topology/overrides:
    get:
      tags:
        - Network Topology
      summary: Get the topology overrides
      operationId: getLinkOverrides
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkOverrides'
        '409':
          description: |-
            The system is currently processing this Snapshot.

            Note: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the
            latest Snapshot is done or to identify an alternate Snapshot that has already been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
    post:
      tags:
        - Network Topology
      summary: Edit the topology overrides
      operationId: editLinkOverrides
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkOverridesEdit'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '409':
          description: |-
            The system is currently processing this Snapshot.

            Note: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the
            latest Snapshot is done or to identify an alternate Snapshot that has already been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
    put:
      tags:
        - Network Topology
      summary: Set the topology overrides
      description: Replaces any topology overrides previously saved for the Snapshot.
      operationId: replaceLinkOverrides
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkOverrides'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '409':
          description: |-
            The system is currently processing this Snapshot.

            Note: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the
            latest Snapshot is done or to identify an alternate Snapshot that has already been processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
components:
  schemas:
    ErrorInfo:
      type: object
      required:
        - httpMethod
        - apiUrl
        - message
      properties:
        httpMethod:
          type: string
          examples:
            - GET
          enum:
            - GET
            - HEAD
            - POST
            - PUT
            - PATCH
            - DELETE
        apiUrl:
          type: string
          examples:
            - /api/version
        message:
          type: string
          description: A description of the error
        reason:
          type: string
    LinkOverrides:
      type: object
      properties:
        absent:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        present:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    LinkOverridesEdit:
      type: object
      properties:
        absentAdditions:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        absentRemovals:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        presentAdditions:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        presentRemovals:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    TopologyLink:
      type: object
      properties:
        sourcePort:
          type: string
        targetPort:
          type: string
    Link:
      type: object
      properties:
        port1:
          type: string
        port2:
          type: string
  securitySchemes:
    api_token:
      type: http
      scheme: basic
