swagger: '2.0'
info:
  version: 2023-03-01-preview
  title: Microsoft Azure Azure Maps Routeset Service.
  description: APIs for managing routesets.
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/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.


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


      #### Notes

      * 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).

      * 

      The `Authorization URL` is specific to the Azure public cloud instance.
      Sovereign clouds have unique Authorization URLs and Azure Active directory
      configurations. 

      * 

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

      * 

      Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for
      configuration based setup of an application for multiple use cases.

      * Currently, Azure Active Directory [v1.0 or
      v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison)
      supports Work, School, and Guests but does not support Personal accounts.
    scopes:
      https://atlas.microsoft.com/.default: https://atlas.microsoft.com/.default
  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.

       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.

       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.

       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.

       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
security:
  - AADToken:
      - https://atlas.microsoft.com/.default
  - SharedKey: []
  - SasToken: []
definitions:
  FacilityDetails:
    description: Details about each facility in the routeset.
    type: object
    properties:
      facilityId:
        description: The identifier of the structure this routeset was created from.
        type: string
        readOnly: true
      levelOrdinals:
        description: The level identifiers within this facility.
        type: array
        items:
          type: number
        x-ms-identifiers: []
        readOnly: true
  RoutesetsList:
    description: >-
      The response model for the Routeset List API. Returns the list of all
      routesets.
    type: object
    properties:
      routesets:
        description: The list of all routesets.
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/Routeset'
      nextLink:
        description: If present, the location of the next page of data.
        type: string
        readOnly: true
  Routeset:
    description: Detailed information for the routeset.
    type: object
    properties:
      routesetId:
        description: The unique ID of the routeset.
        type: string
        readOnly: true
      datasetId:
        description: The ID of the dataset used to create this routeset.
        type: string
        readOnly: true
      description:
        description: >-
          The description code for the building with the ontology version
          number.
        type: string
        readOnly: true
      facilities:
        description: The facility information and building level ordinal numbers.
        type: array
        items:
          $ref: '#/definitions/FacilityDetails'
        x-ms-identifiers: []
        readOnly: true
      created:
        description: The date and time the routeset object was created.
        type: string
        format: date-time
        readOnly: true
parameters:
  ApiVersion:
    name: api-version
    description: Version number of Azure Maps API.
    type: string
    in: query
    required: true
    x-ms-parameter-location: client
  RouteDatasetId:
    name: datasetId
    type: string
    in: query
    description: >-
      The ID of the dataset from which to create the routeset(s). A routeset is
      created for each facility in the dataset.
    required: true
    x-ms-parameter-location: method
  Description:
    name: description
    description: User provided description of the routeset.
    type: string
    in: query
    x-ms-parameter-location: client
  QueryRoutesetId:
    name: routesetId
    description: The ID of the routeset to query for.
    type: string
    in: path
    required: true
    x-ms-parameter-location: method
  DeleteRoutesetId:
    name: routesetId
    description: The ID of the routeset to delete.
    type: string
    in: path
    required: true
    x-ms-parameter-location: method
  OperationId:
    name: operationId
    description: The ID used to query the status of the routeset creation.
    type: string
    in: path
    required: true
    x-ms-parameter-location: method
paths:
  /routesets:
    post:
      summary: 'Microsoft Azure Use To Create A Routeset'
      description: >-
        <br><br>The `Create` API is an HTTP `POST` request that allows the
        caller to create a routeset from a dataset. The routeset is a data
        structure consumed by the Azure Maps
        [Wayfinding](/rest/api/maps-creator/wayfinding) service to discover the
        shortest paths within a facility.<br><br>The Create Routeset API is a
        [long-running
        operation](https://aka.ms/am-creator-lrt-v2).<br><br>Creator makes it
        possible to develop applications based on your private indoor map data
        using Azure Maps API and SDKs. See the [Creator for indoor
        maps](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps)
        article for an introduction to the Azure Maps Creator concepts and
        tools.<br><br>### Submit Create Request<br><br>To create a routeset,
        make a `POST` request with an empty body. The dataset is used as the
        source of the routeset data, so the `datasetId` query parameter must be
        included.
      operationId: microsoftAzureRoutesetCreate
      x-ms-long-running-operation: true
      x-ms-long-running-operation-options:
        final-state-via: location
      x-ms-examples:
        'Create a routeset from a previously created dataset ':
          $ref: ./examples/wayfind/Routeset_Create.json
      parameters:
        - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/RouteDatasetId'
        - $ref: '#/parameters/Description'
      responses:
        '202':
          $ref: ../../../Common/preview/1.0/common.json#/responses/202AsyncV2
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
        - Routesets
    get:
      summary: 'Microsoft Azure Use To Get A List Of Routesets'
      description: >-
        <br><br>Creator makes it possible to develop applications based on your
        private indoor map data using Azure Maps API and SDKs. See the [Creator
        for indoor
        maps](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps)
        article for an introduction to the Azure Maps Creator concepts and
        tools.<br><br>### Submit List Request<br><br>The `List` API is an HTTP
        `GET` request that allows the caller to fetch a list of all routesets in
        the current Azure Maps Creator account.
      operationId: microsoftAzureRoutesetList
      x-ms-examples:
        Enumerate all routesets for a given subscription:
          $ref: ./examples/wayfind/Routeset_List.json
      parameters:
        - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
        - $ref: '#/parameters/ApiVersion'
      x-ms-pageable:
        itemName: routesets
        nextLinkName: nextLink
      responses:
        '200':
          description: >-
            List routeset request completed successfully. The response body
            contains a list of all routesets.
          schema:
            $ref: '#/definitions/RoutesetsList'
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
        - Routesets
  /routesets/{routesetId}:
    get:
      summary: 'Microsoft Azure Use To Get The Details Of A Routeset'
      description: >-
        <br><br>Creator makes it possible to develop applications based on your
        private indoor map data using Azure Maps API and SDKs. See the [Creator
        for indoor
        maps](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps)
        article for an introduction to the Azure Maps Creator concepts and
        tools.<br><br>### Submit Get Request<br><br>The `Get` API is an HTTP
        `GET` request that allows the caller to fetch the details of an existing
        routeset, specified by the `routesetId`.
      operationId: microsoftAzureRoutesetGet
      x-ms-examples:
        Get details for a previously created dataset:
          $ref: ./examples/wayfind/Routeset_Get.json
      parameters:
        - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/QueryRoutesetId'
      responses:
        '200':
          description: The get routeset request completed successfully.
          schema:
            $ref: '#/definitions/Routeset'
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
        - Routesets
    delete:
      summary: 'Microsoft Azure Use To Delete A Routeset'
      description: >-
        <br><br>Creator makes it possible to develop applications based on your
        private indoor map data using Azure Maps API and SDKs. See the [Creator
        for indoor
        maps](https://docs.microsoft.com/azure/azure-maps/creator-indoor-maps)
        article for an introduction to the Azure Maps Creator concepts and
        tools.<br><br>### Submit Delete Request<br><br>The `Delete` API is an
        HTTP `DELETE` request sent with the `routesetId` of the routeset to
        delete.
      operationId: microsoftAzureRoutesetDelete
      x-ms-examples:
        Delete an existing routeset:
          $ref: ./examples/wayfind/Routeset_Delete.json
      parameters:
        - $ref: '#/parameters/DeleteRoutesetId'
        - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
        - $ref: '#/parameters/ApiVersion'
      responses:
        '204':
          description: Routeset delete request completed successfully.
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
        - Routesets
  /routesets/operations/{operationId}:
    get:
      summary: 'Microsoft Azure Use To Check The Status Of The Routeset Creation Process'
      description: >-
        <br><br>The `Get Operation` API is an HTTP `GET` request used to check
        the status of the routeset creation process and retrieve the
        `routesetId`.<br><br>### Submit Operations Request<br><br>To view the
        current progress of a routeset operation, you will use a `GET` request
        where the `operationId` given the path is the ID that represents the
        operation.<br><br>### Operation Response<br><br>While in progress, a
        `200-OK` http status code is returned with no extra headers. If the
        operation succeeds, a `200-OK` http status code is returned with the
        `Resource-Location` in the header.
      operationId: microsoftAzureRoutesetGetoperation
      x-ms-examples:
        Get the status of an operation which is still running:
          $ref: ./examples/wayfind/Routeset_GetOperationStillRunning.json
        Get the status of an operation which has finished successfully:
          $ref: ./examples/wayfind/Routeset_GetOperation.json
      parameters:
        - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/OperationId'
      responses:
        '200':
          description: >-
            The operation is running or complete. If the operation was
            successful, use the Resource-Location header to obtain the path to
            the result.
          schema:
            $ref: ./tileset.json#/definitions/LongRunningOperationResult
          headers:
            Resource-Location:
              type: string
              description: >-
                If successful, a URI where details on the newly created resource
                can be found.
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      tags:
        - Routesets
tags:
  - name: Routesets