{ "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\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Alias TypeJSONNotes
Devices\n ```\n {\n \"name\": \"tor_switches\",\n \"type\": \"DEVICES\",\n \"values\": [\"dc?-tor*\", \"tor-*\"]\n }\n ```\n \n The `values` are device names and/or name patterns containing glob wildcards\n (e.g. `*`,`?`, `[abc]`, `[0‑9]`).\n
Interfaces\n ```\n {\n \"name\": \"vlan_20_access\",\n \"type\": \"INTERFACES\",\n \"values\": [\"SF-ACC-0-8 et[12]\"]\n }\n ```\n \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
\n ```\n {\n \"name\": \"vlan_20_to_29_access\",\n \"type\": \"INTERFACES\",\n \"vlanIds\": [\"20-29\"],\n \"vlanIntfTypes\": [\"ACCESS\"]\n }\n ```\n \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
Hosts\n ```\n {\n \"name\": \"web_servers\",\n \"type\": \"HOSTS\",\n \"values\": [\"10.30.1.0/24\"],\n \"locations\": [\"tor_switches\"]\n }\n ```\n \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
Header Values\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 \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
\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.\n\nNote: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the\nlatest 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\n`?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.\n\nNote: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the\nlatest 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.\n\nNote: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the\nlatest 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.\n\nNote: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the\nlatest 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" } } } }