{
  "openapi": "3.1.0",
  "info": {
    "title": "Forward Networks: Network Locations API",
    "description": "Get, create, update, or delete a network's user-defined locations",
    "contact": {
      "email": "support@forwardnetworks.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://spdx.org/licenses/MIT"
    },
    "version": "${apiVersion}"
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "security": [
    {
      "api_token": []
    }
  ],
  "tags": [
    {
      "name": "Network Locations",
      "description": "Get, create, update, or delete a network's user-defined locations"
    }
  ],
  "paths": {
    "/api/networks/{networkId}/atlas": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Gets 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": "getAtlasUsingGET",
        "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": "Updates 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": "updateAtlasUsingPATCH",
        "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": {}
          }
        }
      }
    },
    "/api/networks/{networkId}/locations": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Gets a network’s locations",
        "operationId": "getLocationsUsingGET",
        "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": "Creates a network location",
        "operationId": "addLocationUsingPOST",
        "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": "Creates 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": "putLocationsUsingPUT",
        "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": "Creates or updates network locations",
        "description": "Any patches that specify an existing location’s `id` will update the existing location. Any other patches will each create a new location. Patches are applied sequentially.",
        "operationId": "patchLocationsUsingPATCH",
        "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": {}
          }
        }
      }
    },
    "/api/networks/{networkId}/locations/{locationId}": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Gets a network location",
        "operationId": "getLocationUsingGET",
        "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"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Deletes a network location",
        "description": "When a location with devices is deleted, all of its devices will be unassigned.",
        "operationId": "deleteLocationUsingDELETE",
        "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": {}
          }
        }
      },
      "patch": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Updates a network location",
        "description": "All JSON properties in the request body are optional. Include only the properties you wish to change.",
        "operationId": "patchLocationUsingPATCH",
        "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"
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{networkId}/locations/{locationId}/clusters": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Gets the device clusters at a location",
        "operationId": "getDeviceClustersUsingGET",
        "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": "Creates a device cluster at a location",
        "operationId": "addDeviceClusterUsingPOST",
        "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": "Replaces all device clusters at a location",
        "operationId": "putDeviceClustersUsingPUT",
        "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": {}
          }
        }
      }
    },
    "/api/networks/{networkId}/locations/{locationId}/clusters/{clusterName}": {
      "get": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Gets a device cluster",
        "operationId": "getDeviceClusterUsingGET",
        "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"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Deletes a device cluster",
        "operationId": "deleteDeviceClusterUsingDELETE",
        "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": {}
          }
        }
      },
      "patch": {
        "tags": [
          "Network Locations"
        ],
        "summary": "Updates a device cluster",
        "description": "All JSON properties in the request body are optional. Include only the properties you wish to change.",
        "operationId": "updateDeviceClusterUsingPATCH",
        "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": {}
          }
        }
      }
    }
  },
  "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\n- atl-edge-fw02\n- atl-isp-edge01\n- atl-isp-edge02"
            ]
          }
        }
      },
      "DeviceClusterUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "examples": [
              "atl-edge"
            ]
          },
          "devices": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [
              "- atl-edge-fw01\n- atl-edge-fw02\n- atl-isp-edge01\n- 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` is specified.",
            "examples": [
              "Dayton"
            ]
          },
          "adminDivision": {
            "type": "string",
            "description": "Name of the administrative division (district, province, region, state, territory, etc.) that `city` is in (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` is 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 (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 (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` is specified.",
            "examples": [
              "Dayton"
            ]
          },
          "adminDivision": {
            "type": "string",
            "description": "Name of the administrative division (district, province, region, state, territory, etc.) that `city` is in (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` is specified.",
            "examples": [
              "United States"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "api_token": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}