Microsoft Azure Feature State Sets API

openapi: 3.2.0
info:
  title: Microsoft Azure Azure Maps Feature State Service Feature…
  version: '2.0'
  description: APIs for managing the dynamic feature states in Azure Maps.
security:
- AADToken:
  - https://atlas.microsoft.com/.default
- SharedKey: []
- SasToken: []
tags:
- name: featureStateSets
paths:
  /featureStateSets:
    post:
      x-publish: true
      description: '**Applies to:** see pricing tiers.


        Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. This article introduces concepts and tools that apply to Azure Maps Creator.


        This POST API allows the user to create a new Stateset and define stateset style using request body.


        Creator 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.


        The 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.


        This Feature State service pivot on the Stateset. Like Tileset, Stateset encapsulates the storage mechanism for feature states for a dataset.


        Once 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.


        Feature 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.


        Azure 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: microsoftAzureFeaturestateCreatestateset
      x-ms-examples:
        Create a new stateset with a datasetId:
          $ref: ./examples/CreateStateset.json
      parameters:
      - $ref: '#/components/parameters/SubscriptionKey'
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/DatasetIdForCreate'
      - $ref: '#/components/parameters/FeatureStateSetDescription'
      responses:
        '200':
          description: Stateset created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatesetCreatedResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Microsoft Azure Post Featurestatesets
      tags:
      - featureStateSets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StylesObject'
        description: The stateset style JSON data.
        required: true
    get:
      x-publish: true
      description: '**Applies to:** see pricing tiers.


        Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. This article introduces concepts and tools that apply to Azure Maps Creator.


        This API allows the caller to fetch a list of all previously successfully created statesets.'
      operationId: microsoftAzureFeaturestateListstateset
      x-ms-examples:
        List all the previously created statesets:
          $ref: ./examples/Stateset_List.json
      parameters:
      - $ref: '#/components/parameters/SubscriptionKey'
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: The list stateset request completed successfully. The response body contains a list of all the previously created statesets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatesetListResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Microsoft Azure Get Featurestatesets
      tags:
      - featureStateSets
  /featureStateSets/{statesetId}:
    put:
      x-publish: true
      description: '**Applies to:** see pricing tiers.


        Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. This article introduces concepts and tools that apply to Azure Maps Creator.


        This PUT API allows the user to update the stateset style rules.'
      operationId: microsoftAzureFeaturestatePutstateset
      x-ms-examples:
        Update stateset style rules with a statesetId:
          $ref: ./examples/UpdateStateset.json
      parameters:
      - $ref: '#/components/parameters/SubscriptionKey'
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/StatesetIdInPath'
      responses:
        '200':
          description: Stateset styles are updated successfully.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Microsoft Azure Put Featurestatesets Statesetid
      tags:
      - featureStateSets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StylesObject'
        description: The stateset style JSON data. Only style rules are allowed to be updated, update on keyname and type is not allowed.
        required: true
    delete:
      x-publish: true
      description: '**Applies to:** see pricing tiers.


        Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. This article introduces concepts and tools that apply to Azure Maps Creator.


        This DELETE API allows the user to delete the stateset and the associated data.'
      operationId: microsoftAzureFeaturestateDeletestateset
      x-ms-examples:
        Delete an existing stateset:
          $ref: ./examples/DeleteStateset.json
      parameters:
      - $ref: '#/components/parameters/SubscriptionKey'
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/StatesetIdInPath'
      responses:
        '204':
          description: Stateset Deleted.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Microsoft Azure Delete Featurestatesets Statesetid
      tags:
      - featureStateSets
    get:
      x-publish: true
      description: '**Applies to:** see pricing tiers.


        Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. This article introduces concepts and tools that apply to Azure Maps Creator.


        This GET API allows the user to get the stateset Information.


        The stateset Information includes the datasetId associated to the stateset, and the styles of that stateset.'
      operationId: microsoftAzureFeaturestateGetstateset
      x-ms-examples:
        Get stateset information with a statesetId:
          $ref: ./examples/GetStateset.json
      parameters:
      - $ref: '#/components/parameters/SubscriptionKey'
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/StatesetIdInPath'
      responses:
        '200':
          description: Get request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatesetGetResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Microsoft Azure Get Featurestatesets Statesetid
      tags:
      - featureStateSets
  /featureStateSets/{statesetId}/featureStates/{featureId}:
    put:
      x-publish: true
      operationId: microsoftAzureFeaturestateUpdatestates
      description: '**Applies to:** see pricing tiers.


        Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. This article introduces concepts and tools that apply to Azure Maps Creator.


        This 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/UpdateStates.json
      parameters:
      - $ref: '#/components/parameters/SubscriptionKey'
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/StatesetIdInPath'
      - $ref: '#/components/parameters/FeatureIdSet'
      responses:
        '200':
          description: Feature states are updated successfully.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Microsoft Azure Put Featurestatesets Statesetid Featurestates Featureid
      tags:
      - featureStateSets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeatureStatesStructure'
        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
    delete:
      x-publish: true
      operationId: microsoftAzureFeaturestateDeletestate
      description: '**Applies to:** see pricing tiers.


        Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. This article introduces concepts and tools that apply to Azure Maps Creator.


        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/DeleteFeatureState.json
      parameters:
      - $ref: '#/components/parameters/SubscriptionKey'
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/StatesetIdInPath'
      - $ref: '#/components/parameters/FeatureIdDelete'
      - $ref: '#/components/parameters/StateKeyNameDelete'
      responses:
        '204':
          description: Feature states deleted successfully.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
      summary: Microsoft Azure Delete Featurestatesets Statesetid Featurestates Featureid
      tags:
      - featureStateSets
    get:
      x-publish: true
      operationId: microsoftAzureFeaturestateGetstates
      description: '**Applies to:** see pricing tiers.


        Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. This article introduces concepts and tools that apply to Azure Maps Creator.


        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/GetStates.json
      parameters:
      - $ref: '#/components/parameters/SubscriptionKey'
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/StatesetIdInPath'
      - $ref: '#/components/parameters/FeatureIdGet'
      responses:
        '200':
          description: Get request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureStatesStructure'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Microsoft Azure Get Featurestatesets Statesetid Featurestates Featureid
      tags:
      - featureStateSets
components:
  parameters:
    SubscriptionKey:
      name: subscription-key
      description: One of the Azure Maps keys provided from an Azure Map Account. Please refer to this [article](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication) for details on how to manage authentication.
      in: query
      required: false
      x-ms-parameter-location: client
      schema:
        type: string
    StateKeyNameDelete:
      name: stateKeyName
      description: The Name of the state to be deleted.
      in: query
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    StatesetIdInPath:
      name: statesetId
      description: The stateset id that was created.
      in: path
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    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.
      in: query
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    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.
      in: path
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    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.
      in: path
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    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.
      in: path
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    FeatureStateSetDescription:
      name: description
      description: Description for the stateset. Max length allowed is 1000.
      in: query
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    ApiVersion:
      name: api-version
      description: Version number of Azure Maps API. Current version is 2.0
      in: query
      required: true
      x-ms-parameter-location: client
      schema:
        type: string
        default: '2.0'
  responses:
    '403':
      description: Permission, capacity, or authentication issues.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
    '401':
      description: Access denied due to invalid subscription key or invalid Microsoft Entra ID bearer token.  Make sure to provide a valid key for an active Azure subscription and Maps resource.  Otherwise, verify the [WWW-Authenticate](https://tools.ietf.org/html/rfc6750#section-3.1) header for error code and description of the provided Microsoft Entra ID bearer token.
      headers:
        WWW-Authenticate:
          description: Bearer realm="https://atlas.microsoft.com/", error="invalid_token", error_description="The access token expired"
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
    '500':
      description: An error occurred while processing the request. Please try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
    '400':
      description: 'Bad request: one or more parameters were incorrectly specified or are mutually exclusive.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
    '404':
      description: 'Not Found: the requested resource could not be found, but it may be available again in the future.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
    '409':
      description: The request could not be completed due to a conflict with the current state of the resource. Likely caused by a parallel update to the same resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
  schemas:
    ODataError:
      type: object
      description: This object is returned when an error occurs in the Azure Maps API.
      properties:
        code:
          type: string
          readOnly: true
          description: The ODataError code.
        message:
          type: string
          readOnly: true
          description: If available, a human-readable description of the error.
        details:
          type: array
          items:
            $ref: '#/components/schemas/ODataError'
        target:
          type: string
          readOnly: true
          description: If available, the target causing the error.
    ODataErrorResponse:
      type: object
      description: This response object is returned when an error occurs in the Azure Maps API.
      properties:
        error:
          $ref: '#/components/schemas/ODataError'
    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: '#/components/schemas/StylesObject'
    FeatureStatesStructure:
      description: The feature states model for a feature.
      type: object
      properties:
        states:
          description: The feature states array.
          type: array
          items:
            $ref: '#/components/schemas/FeatureStateObject'
    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: '#/components/schemas/StyleObject'
    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: object
        eventTimestamp:
          description: Valid Timestamp when the feature state was captured.
          type: string
    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
    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). '
      type: object
    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: '#/components/schemas/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: '#/components/schemas/StylesObject'
  securitySchemes:
    AADToken:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://atlas.microsoft.com/.default: https://atlas.microsoft.com/.default
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: "These are the [Microsoft Entra OAuth 2.0](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/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 Microsoft Entra ID 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* For more information on Microsoft identity platform, see [Microsoft identity platform overview](https://learn.microsoft.com/entra/identity-platform/v2-overview)."
    SharedKey:
      type: apiKey
      description: "This is a shared key that is provisioned when you [Create an Azure Maps account](https://docs.microsoft.com/azure/azure-maps/quick-demo-map-app#create-an-azure-maps-account) in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.\n\n With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.\n\n For publicly exposed applications, our recommendation is to use the [confidential client applications](https://docs.microsoft.com/azure/azure-maps/authentication-best-practices#confidential-client-applications) approach to access Azure Maps REST APIs so your key can be securely stored."
      name: subscription-key
      in: query
    SasToken:
      type: apiKey
      description: "This is a shared access signature token is created from the List SAS operation on the [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 token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.\n\n For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the [Map account resource](https://aka.ms/amauth) to limit rendering abuse and regularly renew the SAS Token."
      name: SAS Token
      in: header
x-ms-parameterized-host:
  hostTemplate: '{geography}.atlas.microsoft.com'
  parameters:
  - $ref: '#/components/parameters/GeographicResourceLocation'