featurestate.json

{
  "swagger": "2.0",
  "info": {
    "title": "Azure Maps Feature State Service",
    "version": "2.0",
    "description": "APIs for managing the dynamic feature states in Azure Maps."
  },
  "x-ms-parameterized-host": {
    "hostTemplate": "{geography}.atlas.microsoft.com",
    "parameters": [
      {
        "$ref": "../../../Common/preview/1.0/common.json#/parameters/GeographicResourceLocation"
      }
    ]
  },
  "schemes": [
    "https"
  ],
  "consumes": [],
  "produces": [
    "application/json"
  ],
  "securityDefinitions": {
    "AADToken": {
      "type": "oauth2",
      "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
      "flow": "implicit",
      "description": "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-overview)  Flows. When paired with [Azure role-based access](https://docs.microsoft.com/en-us/azure/role-based-access-control/overview)  control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a  built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution  for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to.  This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently, Azure Active Directory [v1.0](https://docs.microsoft.com/en-us/azure/active-directory/develop/azure-ad-endpoint-comparison) tokens are supported.",
      "scopes": {
        "https://atlas.microsoft.com/.default": "https://atlas.microsoft.com/.default"
      }
    },
    "AzureKey": {
      "type": "apiKey",
      "description": "This is a shared key that is provisioned when creating an [Azure Maps resource](https://aka.ms/amauth) through the Azure management plane  via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n\n With this key, any application is authorized to access  all REST APIs. In other words, these can currently be treated as master keys to the account which they are issued for.\n\n For publicly exposed applications, our recommendation is to use server-to-server access of Azure Maps REST APIs where this key can be  securely stored.",
      "name": "subscription-key",
      "in": "header"
    }
  },
  "security": [
    {
      "AADToken": [
        "https://atlas.microsoft.com/.default"
      ]
    },
    {
      "AzureKey": []
    }
  ],
  "responses": {},
  "parameters": {
    "FeaturestateApiVersionV2": {
      "name": "api-version",
      "description": "Version number of Azure Maps API.",
      "type": "string",
      "in": "query",
      "required": true,
      "default": "2.0",
      "x-ms-parameter-location": "client"
    },
    "FeatureStateSetDescription": {
      "name": "description",
      "description": "Description for the stateset. Max length allowed is 1000.",
      "type": "string",
      "in": "query",
      "required": false,
      "x-ms-parameter-location": "method"
    },
    "DatasetIdForCreate": {
      "name": "datasetId",
      "description": "The datasetId must have been obtained from a successful [Dataset Create API](https://docs.microsoft.com/en-us/rest/api/maps/v2/dataset/create) call.",
      "type": "string",
      "in": "query",
      "required": true,
      "x-ms-parameter-location": "method"
    },
    "StatesetIdInPath": {
      "name": "statesetId",
      "description": "The stateset id that was created.",
      "type": "string",
      "in": "path",
      "required": true,
      "x-ms-parameter-location": "method"
    },
    "FeatureIdSet": {
      "name": "featureId",
      "description": "The id of a feature in the given dataset. If the featureId is not present in the dataset, Bad Request response will be returned.",
      "type": "string",
      "in": "path",
      "required": true,
      "x-ms-parameter-location": "method"
    },
    "FeatureIdGet": {
      "name": "featureId",
      "description": "The id of a feature in the given stateset. If no state was set for the featureId in the stateset earlier, Bad Request response will be returned.",
      "type": "string",
      "in": "path",
      "required": true,
      "x-ms-parameter-location": "method"
    },
    "FeatureIdDelete": {
      "name": "featureId",
      "description": "The id of a feature in the given stateset. If no state was set for the featureId in the stateset earlier, Bad Request response will be returned.",
      "type": "string",
      "in": "path",
      "required": true,
      "x-ms-parameter-location": "method"
    },
    "StateKeyNameDelete": {
      "name": "stateKeyName",
      "description": "The Name of the state to be deleted.",
      "type": "string",
      "in": "query",
      "required": true,
      "x-ms-parameter-location": "method"
    }
  },
  "paths": {
    "/featureStateSets": {
      "post": {
        "description": "**Applies to:** see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps) article introduces concepts and tools that apply to Azure Maps Creator.\n\nThis POST API allows the user to create a new Stateset and define stateset style using request body.\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. The Feature State API is part of Creator. \n\nThe Feature State service allows the user to update the states of a feature and query them to be used in other services. The dynamic properties of a feature that don't belong to the dataset are referred to as *states* here.\n\nThis Feature State service pivot on the Stateset. Like Tileset, Stateset encapsulates the storage mechanism for feature states for a dataset.\n\nOnce the stateset is created, users can use that statesetId to post feature state updates and retrieve the current feature states. A feature can have only one state at a given point in time. \n\nFeature state is defined by the key name, value and the timestamp. When a feature state update is posted to Azure Maps, the state value gets updated only if the provided state’s timestamp is later than the stored timestamp. \n\nAzure Maps MapControl provides a way to use these feature states to style the features. Please refer to the State Tile documentation for more information.",
        "operationId": "FeatureState_CreateStateset",
        "x-ms-examples": {
          "Create a new stateset with a datasetId": {
            "$ref": "./examples/featurestate/Featurestate_CreateStateset.json"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/FeaturestateApiVersionV2"
          },
          {
            "$ref": "#/parameters/DatasetIdForCreate"
          },
          {
            "$ref": "#/parameters/FeatureStateSetDescription"
          },
          {
            "name": "statesetCreateRequestBody",
            "in": "body",
            "description": "The stateset style JSON data.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/StylesObject"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stateset created.",
            "schema": {
              "$ref": "#/definitions/StatesetCreatedResponse"
            }
          },
          "default": {
            "$ref": "../../../Common/preview/1.0/common.json#/responses/default"
          }
        }
      },
      "get": {
        "description": "**Applies to:** see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps) article introduces concepts and tools that apply to Azure Maps Creator.\n\n This API allows the caller to fetch a list of all previously successfully created statesets.",
        "operationId": "FeatureState_ListStateset",
        "x-ms-examples": {
          "List all the previously created statesets": {
            "$ref": "./examples/featurestate/Featurestate_List.json"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/FeaturestateApiVersionV2"
          }
        ],
        "x-ms-pageable": {
          "itemName": "statesets",
          "nextLinkName": "nextLink"
        },
        "responses": {
          "200": {
            "description": "The list stateset request completed successfully. The response body contains a list of all the previously created statesets.",
            "schema": {
              "$ref": "#/definitions/StatesetListResponse"
            }
          },
          "default": {
            "$ref": "../../../Common/preview/1.0/common.json#/responses/default"
          }
        }
      }
    },
    "/featureStateSets/{statesetId}": {
      "put": {
        "description": "**Applies to:** see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps) article introduces concepts and tools that apply to Azure Maps Creator.\n\nThis PUT API allows the user to update the stateset style rules.",
        "operationId": "FeatureState_PutStateset",
        "x-ms-examples": {
          "Update stateset style rules with a statesetId": {
            "$ref": "./examples/featurestate/Featurestate_UpdateStateset.json"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/FeaturestateApiVersionV2"
          },
          {
            "$ref": "#/parameters/StatesetIdInPath"
          },
          {
            "name": "statesetStyleUpdateRequestBody",
            "in": "body",
            "description": "The stateset style JSON data. Only style rules are allowed to be updated, update on keyname and type is not allowed.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/StylesObject"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stateset styles are updated successfully."
          },
          "default": {
            "$ref": "../../../Common/preview/1.0/common.json#/responses/default"
          }
        }
      },
      "delete": {
        "description": "**Applies to:** see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps) article introduces concepts and tools that apply to Azure Maps Creator.\n\n This DELETE API allows the user to delete the stateset and the associated data.",
        "operationId": "FeatureState_DeleteStateset",
        "x-ms-examples": {
          "Delete an existing stateset": {
            "$ref": "./examples/featurestate/Featurestate_DeleteStateset.json"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/FeaturestateApiVersionV2"
          },
          {
            "$ref": "#/parameters/StatesetIdInPath"
          }
        ],
        "responses": {
          "204": {
            "description": "Stateset Deleted."
          },
          "default": {
            "$ref": "../../../Common/preview/1.0/common.json#/responses/default"
          }
        }
      },
      "get": {
        "description": "**Applies to:** see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps) article introduces concepts and tools that apply to Azure Maps Creator.\n\nThis GET API allows the user to get the stateset Information.\n\nThe stateset Information includes the datasetId associated to the stateset, and the styles of that stateset.",
        "operationId": "FeatureState_GetStateset",
        "x-ms-examples": {
          "Get stateset information with a statesetId": {
            "$ref": "./examples/featurestate/Featurestate_GetStateset.json"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/FeaturestateApiVersionV2"
          },
          {
            "$ref": "#/parameters/StatesetIdInPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Get request completed successfully.",
            "schema": {
              "$ref": "#/definitions/StatesetGetResponse"
            }
          },
          "default": {
            "$ref": "../../../Common/preview/1.0/common.json#/responses/default"
          }
        }
      }
    },
    "/featureStateSets/{statesetId}/featureStates/{featureId}": {
      "put": {
        "operationId": "FeatureState_UpdateStates",
        "description": "**Applies to:** see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps) article introduces concepts and tools that apply to Azure Maps Creator.\n\nThis PUT API allows the user to update the state of the given feature in the given stateset.",
        "x-ms-examples": {
          "Update the states of a feature": {
            "$ref": "./examples/featurestate/Featurestate_UpdateStates.json"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/FeaturestateApiVersionV2"
          },
          {
            "$ref": "#/parameters/StatesetIdInPath"
          },
          {
            "$ref": "#/parameters/FeatureIdSet"
          },
          {
            "name": "featureStateUpdateRequestBody",
            "in": "body",
            "description": "The feature state JSON data. A feature can have only one state at a given point in time. The specified state keyname must have been defined during the stateset creation.",
            "required": true,
            "schema": {
              "$ref": "#/definitions/FeatureStatesStructure"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Feature states are updated successfully."
          },
          "default": {
            "$ref": "../../../Common/preview/1.0/common.json#/responses/default"
          }
        }
      },
      "delete": {
        "operationId": "FeatureState_DeleteState",
        "description": "**Applies to:** see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps) article introduces concepts and tools that apply to Azure Maps Creator.\n\n This API deletes the state information identified by the StateKeyName parameter for the feature identified by the FeatureId parameter in the the stateset.",
        "x-ms-examples": {
          "Delete the given feature state": {
            "$ref": "./examples/featurestate/Featurestate_DeleteFeatureState.json"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/FeaturestateApiVersionV2"
          },
          {
            "$ref": "#/parameters/StatesetIdInPath"
          },
          {
            "$ref": "#/parameters/FeatureIdDelete"
          },
          {
            "$ref": "#/parameters/StateKeyNameDelete"
          }
        ],
        "responses": {
          "204": {
            "description": "Feature states deleted successfully."
          },
          "default": {
            "$ref": "../../../Common/preview/1.0/common.json#/responses/default"
          }
        }
      },
      "get": {
        "operationId": "FeatureState_GetStates",
        "description": "**Applies to:** see pricing [tiers](https://aka.ms/AzureMapsPricingTier).\n\nCreator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. [This](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps) article introduces concepts and tools that apply to Azure Maps Creator.\n\n This API returns the current state information associated with the given feature in the given stateset.",
        "x-ms-examples": {
          "Get the current states of a feature": {
            "$ref": "./examples/featurestate/Featurestate_GetStates.json"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/FeaturestateApiVersionV2"
          },
          {
            "$ref": "#/parameters/StatesetIdInPath"
          },
          {
            "$ref": "#/parameters/FeatureIdGet"
          }
        ],
        "responses": {
          "200": {
            "description": "Get request completed successfully.",
            "schema": {
              "$ref": "#/definitions/FeatureStatesStructure"
            }
          },
          "default": {
            "$ref": "../../../Common/preview/1.0/common.json#/responses/default"
          }
        }
      }
    }
  },
  "definitions": {
    "StatesetGetResponse": {
      "description": "The response model for the successful Stateset Get API.",
      "type": "object",
      "properties": {
        "description": {
          "description": "Description associated with the stateset.",
          "type": "string",
          "readOnly": true
        },
        "datasetIds": {
          "description": "Dataset ID associated with the stateset.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "statesetStyle": {
          "$ref": "#/definitions/StylesObject"
        }
      }
    },
    "StatesetListResponse": {
      "description": "The response model for the successful Stateset List API.",
      "type": "object",
      "properties": {
        "statesets": {
          "description": "A list of statesets information.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/StatesetInfoObject"
          }
        },
        "nextLink": {
          "description": "If present, the location of the next page of data.",
          "type": "string",
          "readOnly": true
        }
      }
    },
    "StatesetInfoObject": {
      "description": "The stateset information detail.",
      "type": "object",
      "properties": {
        "statesetId": {
          "description": "The stateset ID of this stateset.",
          "type": "string"
        },
        "description": {
          "description": "Description associated with the stateset.",
          "type": "string",
          "readOnly": true
        },
        "datasetIds": {
          "description": "Dataset ID associated with the stateset.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "statesetStyle": {
          "$ref": "#/definitions/StylesObject"
        }
      }
    },
    "StatesetCreatedResponse": {
      "description": "The response model for the successful Stateset Create API.",
      "type": "object",
      "properties": {
        "statesetId": {
          "description": "The ID for the new stateset created.",
          "type": "string",
          "readOnly": true
        }
      }
    },
    "FeatureStatesStructure": {
      "description": "The feature states model for a feature.",
      "type": "object",
      "properties": {
        "states": {
          "description": "The feature states array.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/FeatureStateObject"
          }
        }
      }
    },
    "FeatureStateObject": {
      "description": "Single feature state model.",
      "type": "object",
      "properties": {
        "keyName": {
          "description": "Feature state Keyname. Maximum length allowed is 1000.",
          "type": "string"
        },
        "value": {
          "description": "Value for the feature state. Type should comply with the style definition attached to the featurestate. Maximum length allowed for string type is 1024.",
          "type": "string"
        },
        "eventTimestamp": {
          "description": "Valid Timestamp when the feature state was captured.",
          "type": "string"
        }
      }
    },
    "StylesObject": {
      "description": "The styles model.",
      "type": "object",
      "properties": {
        "styles": {
          "description": "An array of stateset styles. The style rule could be a numeric or string or a boolean type style rule.  Refer to NumberRuleObject, StringRuleObject and BooleanRuleObject definitions [here](https://aka.ms/AzureMapsStatesetStylesObject). ",
          "type": "array",
          "items": {
            "$ref": "#/definitions/StyleObject"
          }
        }
      }
    },
    "NumberRuleObject": {
      "description": "The numeric rule. The color is selected from the first range it falls into.",
      "type": "object",
      "properties": {
        "range": {
          "$ref": "#/definitions/RangeObject"
        },
        "color": {
          "description": "The color when value is within the range. Color is a JSON string in a variety of permitted formats, HTML-style hex values, RGB (\"#ff0\", \"#ffff00\", \"rgb(255, 255, 0)\"), RGBA (\"rgba(255, 255, 0, 1)\"), HSL(\"hsl(100, 50%, 50%)\"), and HSLA(\"hsla(100, 50%, 50%, 1)\"). Predefined HTML colors names, like yellow and blue, are also permitted.",
          "type": "string"
        }
      }
    },
    "RangeObject": {
      "description": "The numeric value range for this style rule. If the value is in the range, all the conditions must hold true.",
      "type": "object",
      "properties": {
        "minimum": {
          "description": "All the number x that x ≥ minimum.",
          "type": "string"
        },
        "maximum": {
          "description": "All the number x that x ≤ maximum.",
          "type": "string"
        },
        "exclusiveMinimum": {
          "description": "All the number x that x > exclusiveMinimum.",
          "type": "string"
        },
        "exclusiveMaximum": {
          "description": "All the number x that x < exclusiveMaximum.",
          "type": "string"
        }
      }
    },
    "BooleanRuleObject": {
      "description": "The boolean rule. The color is selected based on the logic value of the key.",
      "type": "object",
      "properties": {
        "true": {
          "description": "The color when value is true. Color is a JSON string in a variety of permitted formats, HTML-style hex values, RGB (\"#ff0\", \"#ffff00\", \"rgb(255, 255, 0)\"), RGBA (\"rgba(255, 255, 0, 1)\"), HSL(\"hsl(100, 50%, 50%)\"), and HSLA(\"hsla(100, 50%, 50%, 1)\"). Predefined HTML colors names, like yellow and blue, are also permitted.",
          "type": "string"
        },
        "false": {
          "description": "The color when value is false. Color is a JSON string in a variety of permitted formats, HTML-style hex values, RGB (\"#ff0\", \"#ffff00\", \"rgb(255, 255, 0)\"), RGBA (\"rgba(255, 255, 0, 1)\"), HSL(\"hsl(100, 50%, 50%)\"), and HSLA(\"hsla(100, 50%, 50%, 1)\"). Predefined HTML colors names, like yellow and blue, are also permitted.",
          "type": "string"
        }
      }
    },
    "StringRuleObject": {
      "description": "The string rule. The string value matching is case sensitive. If a feature's state doesn't match any of the values defined here, that feature will not have any dynamic style. If duplicate string values are given, the first one takes precedence.",
      "type": "object",
      "additionalProperties": {
        "description": "The color when the keyName value string is equal to this property name. Color is a JSON string in a variety of permitted formats, HTML-style hex values, RGB (\"#ff0\", \"#ffff00\", \"rgb(255, 255, 0)\"), RGBA (\"rgba(255, 255, 0, 1)\"), HSL(\"hsl(100, 50%, 50%)\"), and HSLA(\"hsla(100, 50%, 50%, 1)\"). Predefined HTML colors names, like yellow and blue, are also permitted.",
        "type": "string"
      }
    },
    "StyleObject": {
      "description": "The stateset style model. The style rule could be a numeric type style rule or a boolean type style rule.  Refer to NumberRuleObject, StringRuleObject and BooleanRuleObject definitions [here](https://aka.ms/AzureMapsStatesetStylesObject). ",
      "discriminator": "type",
      "type": "object",
      "required": [
        "keyName",
        "type"
      ],
      "properties": {
        "keyName": {
          "description": "Stateset style key name. Key names are random strings but they should be unique inside style array.",
          "type": "string"
        },
        "type": {
          "description": "The type of stateset style.",
          "type": "string",
          "enum": [
            "boolean",
            "number",
            "string"
          ],
          "x-ms-enum": {
            "name": "StyleObjectType",
            "modelAsString": true,
            "values": [
              {
                "value": "boolean",
                "description": "Boolean type of stateset style.",
                "name": "BooleanTypeStyleRule"
              },
              {
                "value": "number",
                "description": "Number type of stateset style.",
                "name": "NumberTypeStyleRule"
              },
              {
                "value": "string",
                "description": "String type of stateset style.",
                "name": "StringTypeStyleRule"
              }
            ]
          }
        }
      }
    },
    "BooleanTypeStyleRule": {
      "description": "The boolean type style rule object.",
      "x-ms-discriminator-value": "boolean",
      "type": "object",
      "allOf": [
        {
          "$ref": "#/definitions/StyleObject"
        }
      ],
      "properties": {
        "rules": {
          "description": "Boolean style rules.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/BooleanRuleObject"
          }
        }
      },
      "required": [
        "rules"
      ]
    },
    "NumberTypeStyleRule": {
      "description": "The numeric type style rule object.",
      "x-ms-discriminator-value": "number",
      "type": "object",
      "allOf": [
        {
          "$ref": "#/definitions/StyleObject"
        }
      ],
      "properties": {
        "rules": {
          "description": "Numeric style rules.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/NumberRuleObject"
          }
        }
      },
      "required": [
        "rules"
      ]
    },
    "StringTypeStyleRule": {
      "description": "The string type style rule object.",
      "x-ms-discriminator-value": "string",
      "type": "object",
      "allOf": [
        {
          "$ref": "#/definitions/StyleObject"
        }
      ],
      "properties": {
        "rules": {
          "description": "String style rules.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/StringRuleObject"
          }
        }
      },
      "required": [
        "rules"
      ]
    }
  }
}