{
  "openapi": "3.1.0",
  "info": {
    "title": "Forward Networks: Network Locations API",
    "summary": "Get, create, update, or delete a network's user-defined locations",
    "description": "Each network has 1) a list of user-defined locations at which devices can be represented in network diagrams and\n2) an _atlas_, which can map each device to a user-defined location. Additionally, devices at the same user-defined\nlocation can be grouped into _device clusters_ to declutter the network diagram.\n\nThe system automatically assigns cloud (AWS/GCP/Azure) devices to predefined cloud locations. All other devices can\nbe assigned to user-defined locations via the atlas. Devices that have no location assigned appear in the default\n(“Unassigned”) location.\n\nWhen creating or updating a user-defined location, you can choose its `id` (like \"sjc-01b\") or allow the system to\ngenerate a numeric one (like \"56\").\n\nA user-chosen location identifier:\n- must not exceed 16 characters,\n- must contain only letters, digits, and hyphens,\n- must begin with a letter,\n- must not end with a hyphen or have consecutive hyphens,\n- must be unique, ignoring case (to avoid confusion), and\n- must be different from the names of other locations, ignoring case (to avoid confusion).\n\nThis section includes:\n- operations for listing, creating, updating, and deleting user-defined locations,\n- operations for retrieving and updating the atlas of device location assignments, and\n- operations for defining and managing device clusters.",
    "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 Locations",
      "description": "Get, create, update, or delete a network's user-defined locations"
    }
  ],
  "paths": {
    "/networks/{networkId}/atlas": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Get device locations",
        "description": "The response is a JSON object that maps device names to their location ids.\n\nSample response: `{\"atl-edge-fw01\": \"2\", \"ny-edge-fw2\": \"1\"}`",
        "operationId": "getAtlas",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Update device locations",
        "description": "The request is a JSON object that maps device names to their new location ids.\n\nSample request: `{\"atl-edge-fw01\": \"2\", \"ny-edge-fw2\": \"1\"}`",
        "operationId": "updateAtlas",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          }
        }
      }
    },
    "/networks/{networkId}/locations": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Get a network’s locations",
        "operationId": "getLocations",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Location"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Create a network location",
        "operationId": "addLocation",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewLocation"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Location"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Create network locations",
        "description": "Creates multiple locations at once. Can be helpful when first setting up a network.\n\nFails (as a precautionary measure) with 409 Conflict if the network already has any network locations.",
        "operationId": "putLocations",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Location"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          },
          "409": {
            "description": "Occurs (as a precautionary measure) if the network already has any network locations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorInfo"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Create or update network locations",
        "description": "Any patches that specify an existing location’s `id` will update the existing location. Any other patches\nwill each create a new location. Patches are applied sequentially.",
        "operationId": "patchLocations",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/LocationBulkPatch"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          }
        }
      }
    },
    "/networks/{networkId}/locations/{locationId}": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Get a network location",
        "operationId": "getLocation",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Location"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Update a network location",
        "description": "All JSON properties in the request body are optional. Include only the properties you wish to\nchange.",
        "operationId": "patchLocation",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LocationPatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Location"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Delete a network location",
        "description": "When a location with devices is deleted, all of its devices will be unassigned.",
        "operationId": "deleteLocation",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          }
        }
      }
    },
    "/networks/{networkId}/locations/{locationId}/clusters": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Get the device clusters at a location",
        "operationId": "getDeviceClusters",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/DeviceCluster"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Create a device cluster at a location",
        "operationId": "addDeviceCluster",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceCluster"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          }
        }
      },
      "put": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Replace all device clusters at a location",
        "operationId": "putDeviceClusters",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/DeviceCluster"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          }
        }
      }
    },
    "/networks/{networkId}/locations/{locationId}/clusters/{clusterName}": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Get a device cluster",
        "operationId": "getDeviceCluster",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "clusterName",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCluster"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Update a device cluster",
        "description": "All JSON properties in the request body are optional. Include only the properties you wish to\nchange.",
        "operationId": "updateDeviceCluster",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "clusterName",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceClusterUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          }
        }
      },
      "delete": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Delete a device cluster",
        "operationId": "deleteDeviceCluster",
        "parameters": [
          {
            "name": "networkId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "clusterName",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DeviceCluster": {
        "type": "object",
        "required": [
          "name",
          "devices"
        ],
        "properties": {
          "name": {
            "type": "string",
            "examples": [
              "atl-edge"
            ]
          },
          "devices": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "atl-edge-fw01",
                "atl-edge-fw02",
                "atl-isp-edge01",
                "atl-isp-edge02"
              ]
            ]
          }
        }
      },
      "DeviceClusterUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "examples": [
              "atl-edge"
            ]
          },
          "devices": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "atl-edge-fw01",
                "atl-edge-fw02",
                "atl-isp-edge01",
                "atl-isp-edge02"
              ]
            ]
          }
        }
      },
      "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"
          }
        }
      },
      "Location": {
        "type": "object",
        "required": [
          "id",
          "name",
          "lat",
          "lng"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "dyt-a"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "Dayton DC"
            ]
          },
          "lat": {
            "type": "number",
            "format": "double",
            "description": "A latitude (geographic coordinate), specified as an angle from -90 to +90 degrees",
            "examples": [
              39.8113
            ]
          },
          "lng": {
            "type": "number",
            "format": "double",
            "description": "A longitude (geographic coordinate), specified as an angle from -180 to +180 degrees",
            "examples": [
              -84.2722
            ]
          },
          "city": {
            "type": "string",
            "description": "Name of the closest city (for display purposes only). Required if `adminDivision` or `country`\nis specified.",
            "examples": [
              "Dayton"
            ]
          },
          "adminDivision": {
            "type": "string",
            "description": "Name of the administrative division (district, province, region, state, territory, etc.) that `city` is in\n(for display purposes only)",
            "examples": [
              "Ohio"
            ]
          },
          "country": {
            "type": "string",
            "description": "Name of the country that `city` is located in (for display purposes only). Required if `city`\nis specified.",
            "examples": [
              "United States"
            ]
          }
        }
      },
      "LocationBulkPatch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the location to update. Required if `name` is absent.",
            "examples": [
              "dyt-a"
            ]
          },
          "name": {
            "type": "string",
            "description": "Name of the location to update or create. Required if `id` is absent.",
            "examples": [
              "Dayton DC"
            ]
          },
          "lat": {
            "type": "number",
            "format": "double",
            "description": "A latitude (geographic coordinate), specified as an angle from -90 to +90 degrees",
            "examples": [
              39.8113
            ]
          },
          "lng": {
            "type": "number",
            "format": "double",
            "description": "A longitude (geographic coordinate), specified as an angle from -180 to +180 degrees",
            "examples": [
              -84.2722
            ]
          },
          "city": {
            "type": "string",
            "description": "Name of the closest city (for display purposes only)",
            "examples": [
              "Dayton"
            ]
          },
          "adminDivision": {
            "type": "string",
            "description": "Name of the administrative division (district, province, region, state, territory, etc.) that `city` is in\n(for display purposes only)",
            "examples": [
              "Ohio"
            ]
          },
          "country": {
            "type": "string",
            "description": "Name of the country that `city` is located in (for display purposes only)",
            "examples": [
              "United States"
            ]
          }
        }
      },
      "LocationPatch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "dyt-a"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "Dayton DC"
            ]
          },
          "lat": {
            "type": "number",
            "format": "double",
            "description": "A latitude (geographic coordinate), specified as an angle from -90 to +90 degrees",
            "examples": [
              39.8113
            ]
          },
          "lng": {
            "type": "number",
            "format": "double",
            "description": "A longitude (geographic coordinate), specified as an angle from -180 to +180 degrees",
            "examples": [
              -84.2722
            ]
          },
          "city": {
            "type": "string",
            "description": "Name of the closest city (for display purposes only)",
            "examples": [
              "Dayton"
            ]
          },
          "adminDivision": {
            "type": "string",
            "description": "Name of the administrative division (district, province, region, state, territory, etc.) that `city` is in\n(for display purposes only)",
            "examples": [
              "Ohio"
            ]
          },
          "country": {
            "type": "string",
            "description": "Name of the country that `city` is located in (for display purposes only)",
            "examples": [
              "United States"
            ]
          }
        }
      },
      "NewLocation": {
        "type": "object",
        "required": [
          "name",
          "lat",
          "lng"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "If absent or null, a numeric identifier will be assigned",
            "examples": [
              "dyt-a"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "Dayton DC"
            ]
          },
          "lat": {
            "type": "number",
            "format": "double",
            "description": "A latitude (geographic coordinate), specified as an angle from -90 to +90 degrees",
            "examples": [
              39.8113
            ]
          },
          "lng": {
            "type": "number",
            "format": "double",
            "description": "A longitude (geographic coordinate), specified as an angle from -180 to +180 degrees",
            "examples": [
              -84.2722
            ]
          },
          "city": {
            "type": "string",
            "description": "Name of the closest city (for display purposes only). Required if `adminDivision` or `country`\nis specified.",
            "examples": [
              "Dayton"
            ]
          },
          "adminDivision": {
            "type": "string",
            "description": "Name of the administrative division (district, province, region, state, territory, etc.) that `city` is in\n(for display purposes only)",
            "examples": [
              "Ohio"
            ]
          },
          "country": {
            "type": "string",
            "description": "Name of the country that `city` is located in (for display purposes only). Required if `city`\nis specified.",
            "examples": [
              "United States"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "api_token": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}