openapi: 3.1.0
info:
  title: 'Forward Networks: Aliases API'
  summary: Define groups of network infrastructure elements or packet header values
  description: "An _Alias_ (or [Object](https://docs.fwd.app/latest/application/objects/)) is a flexible way to group\ninfrastructure elements (like network devices, interfaces, and end hosts) or packet header values (like VLAN IDs, IP\naddresses, and L4 ports). Aliases simplify the definition of policy checks and help when searching the network.\n\nHere are some examples of Alias definitions in JSON.\n<table>\n  <tr>\n    <th>Alias\_Type</th>\n    <th>JSON</th>\n    <th>Notes</th>\n  </tr>\n  <tr>\n    <td>Devices</td>\n    <td>\n      ```\n      {\n        \"name\": \"tor_switches\",\n        \"type\": \"DEVICES\",\n        \"values\": [\"dc?-tor*\", \"tor-*\"]\n       }\n       ```\n    </td>\n    <td>\n      The `values` are device names and/or name patterns containing glob wildcards\n      (e.g.\_`*`,`?`, `[abc]`, `[0‑9]`).\n    </td>\n  </tr>\n  <tr>\n    <td rowspan=\"2\">Interfaces</td>\n    <td>\n        ```\n        {\n          \"name\": \"vlan_20_access\",\n          \"type\": \"INTERFACES\",\n          \"values\": [\"SF-ACC-0-8 et[12]\"]\n        }\n        ```\n    </td>\n    <td>\n      The `values` are device interface names and/or name patterns. Each name or pattern must contain exactly one\n      space, which separates the device name part from the interface name part.\n    </td>\n  </tr>\n  <tr>\n    <td>\n      ```\n      {\n        \"name\": \"vlan_20_to_29_access\",\n        \"type\": \"INTERFACES\",\n        \"vlanIds\": [\"20-29\"],\n        \"vlanIntfTypes\": [\"ACCESS\"]\n      }\n      ```\n    </td>\n    <td>\n      It can be convenient to define a set of device interfaces using a set of VLAN IDs. `vlanIntfTypes` can be\n      `[\"TRUNK\"]`, `[\"ACCESS\"]` or omitted (for both). If `values` is also present, it further restricts the set\n      of matching interfaces.\n    </td>\n  </tr>\n  <tr>\n    <td>Hosts</td>\n    <td>\n      ```\n      {\n        \"name\": \"web_servers\",\n        \"type\": \"HOSTS\",\n        \"values\": [\"10.30.1.0/24\"],\n        \"locations\": [\"tor_switches\"]\n      }\n      ```\n    </td>\n    <td>\n      The `values` are host names, IP\_subnets and/or MAC addresses. The\_`locations` are device or interface\n      names or aliases. At\_least\_one of `locations` and `values` must be specified.\n    </td>\n  </tr>\n  <tr>\n    <td>Header Values</td>\n    <td>\n      ```\n      {\n        \"name\": \"VOIP\",\n        \"type\": \"HEADERS\",\n        \"values\": {\n          \"eth_type\": [\"0x800\"],\n          \"ip_proto\": [\"UDP\"],\n          \"tp_port\": [\"10000\", \"20000\"]\n        }\n      }\n      ```\n    </td>\n    <td>\n        Supported header types are:\n        - `mac_addr` - MAC addresses\n        - `eth_type` - Ethernet types\n        - `vlan_vid` - VLAN IDs/ranges\n        - `ip_addr` - IP addresses/blocks\n        - `ip_proto` - IP protocols\n        - `tp_port` - L4 ports/ranges\n\n        At least one type must be specified.\n    </td>\n  </tr>\n</table>\n\nThe resources below are for reading, creating, updating and deleting the Aliases associated with a network Snapshot.\nChanges to a Snapshot’s Aliases propagate forward to later Snapshots, including future Snapshots."
  contact:
    email: support@forwardnetworks.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  version: ${apiVersion}
servers:
  - url: /api
security:
  - api_token: []
tags:
  - name: Aliases
    description: Define groups of network infrastructure elements or packet header values
paths:
  /snapshots/{snapshotId}/aliases:
    get:
      tags:
        - Aliases
      summary: Get all Aliases
      operationId: getAllAliases
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Aliases'
        '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'
    delete:
      tags:
        - Aliases
      summary: Delete Aliases
      description: |-
        Use the optional `name` parameter to delete only specific Aliases. It can be repeated as in
        `?name=foo&name=bar`. Omit the `name` parameter to delete all Aliases active in the Snapshot.
      operationId: deactivateAliases
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: query
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK. The response contains the deleted Aliases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Aliases'
        '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}/aliases/{name}:
    get:
      tags:
        - Aliases
      summary: Get an Alias
      operationId: getSingleAlias
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AliasAndValue'
        '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:
        - Aliases
      summary: Create an Alias
      operationId: createAlias
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AliasBuilder'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alias'
        '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'
    delete:
      tags:
        - Aliases
      summary: Delete an Alias
      operationId: deactivateAlias
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alias'
components:
  schemas:
    Alias:
      type: object
      required:
        - createdAt
        - creationTime
        - creatorId
        - name
        - type
      properties:
        createdAt:
          type: string
          examples:
            - '2022-04-06T20:34:45.118Z'
        creationTime:
          type: integer
          format: int64
          description: Deprecated for removal in release 26.4. Use `createdAt` instead.
          examples:
            - 1649277285118
        creatorId:
          type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/AliasType'
    AliasAndValue:
      allOf:
        - $ref: '#/components/schemas/Alias'
    AliasBuilder:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - HOSTS
            - DEVICES
            - INTERFACES
            - HEADERS
            - LOGICAL_NETWORK
      oneOf:
        - $ref: '#/components/schemas/HostsAliasBuilder'
        - $ref: '#/components/schemas/DevicesAliasBuilder'
        - $ref: '#/components/schemas/InterfacesAliasBuilder'
        - $ref: '#/components/schemas/TrafficAliasBuilder'
        - $ref: '#/components/schemas/LogicalNetworkAliasBuilder'
      discriminator:
        propertyName: type
        mapping:
          HOSTS: '#/components/schemas/HostsAliasBuilder'
          HostFilter: '#/components/schemas/HostsAliasBuilder'
          DEVICES: '#/components/schemas/DevicesAliasBuilder'
          DeviceFilter: '#/components/schemas/DevicesAliasBuilder'
          INTERFACES: '#/components/schemas/InterfacesAliasBuilder'
          InterfaceFilter: '#/components/schemas/InterfacesAliasBuilder'
          HEADERS: '#/components/schemas/TrafficAliasBuilder'
          PacketFilter: '#/components/schemas/TrafficAliasBuilder'
          LOGICAL_NETWORK: '#/components/schemas/LogicalNetworkAliasBuilder'
    Aliases:
      type: object
      required:
        - aliases
      properties:
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/Alias'
    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
    AliasType:
      type: string
      enum:
        - HOSTS
        - DEVICES
        - INTERFACES
        - HEADERS
        - LOGICAL_NETWORK
    HostsAliasBuilder:
      type: object
      required:
        - name
        - type
      properties:
        locations:
          type: array
          items:
            type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/AliasType'
        values:
          type: array
          items:
            type: string
    DevicesAliasBuilder:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/AliasType'
        values:
          type: array
          items:
            type: string
    InterfacesAliasBuilder:
      type: object
      required:
        - name
        - type
      properties:
        isExposurePoint:
          type: boolean
        name:
          type: string
        type:
          $ref: '#/components/schemas/AliasType'
        values:
          type: array
          items:
            type: string
        vlanIds:
          type: array
          items:
            type: string
        vlanIntfTypes:
          type: array
          items:
            type: string
            enum:
              - ACCESS
              - TRUNK
    TrafficAliasBuilder:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/AliasType'
        values:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    LogicalNetworkAliasBuilder:
      type: object
      required:
        - name
        - type
      properties:
        devices:
          type: array
          items:
            type: string
        edgeNodes:
          type: array
          items:
            type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/AliasType'
  securitySchemes:
    api_token:
      type: http
      scheme: basic
