CommunicationNetworkTraversal.json

{
  "swagger": "2.0",
  "info": {
    "title": "CommunicationNetworkTraversalClient",
    "description": "Azure Communication Network Traversal Service",
    "version": "2022-02-01"
  },
  "paths": {
    "/networkTraversal/:issueRelayConfiguration": {
      "post": {
        "tags": [
          "Turn"
        ],
        "summary": "Issue a configuration for an STUN/TURN server.",
        "operationId": "CommunicationNetworkTraversal_IssueRelayConfiguration",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/ApiVersionParameter"
          },
          {
            "description": "Optional request for providing the id and/or route type for the returned relay configuration.",
            "in": "body",
            "name": "body",
            "schema": {
              "$ref": "#/definitions/CommunicationRelayConfigurationRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "$ref": "#/definitions/CommunicationRelayConfiguration"
            }
          },
          "default": {
            "description": "Error",
            "schema": {
              "$ref": "../../../Common/stable/2021-03-07/common.json#/definitions/CommunicationErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Issue Relay Configuration": {
            "$ref": "./examples/IssueRelayConfiguration.json"
          }
        }
      }
    }
  },
  "definitions": {
    "CommunicationRelayConfigurationRequest": {
      "description": "Request for a CommunicationRelayConfiguration.",
      "type": "object",
      "properties": {
        "id": {
          "description": "An identity to be associated with telemetry for data relayed using the returned credentials. Must be an existing ACS user identity. If not provided, the telemetry will not contain an associated identity value.",
          "type": "string"
        },
        "routeType": {
          "description": "Filter the routing methodology returned. If not provided, will return all route types in separate ICE servers.",
          "$ref": "#/definitions/RouteType"
        }
      }
    },
    "CommunicationIceServer": {
      "description": "An instance of a STUN/TURN server with credentials to be used for ICE negotiation.",
      "required": [
        "credential",
        "urls",
        "username",
        "routeType"
      ],
      "type": "object",
      "properties": {
        "urls": {
          "description": "List of STUN/TURN server URLs.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "username": {
          "description": "User account name which uniquely identifies the credentials.",
          "type": "string"
        },
        "credential": {
          "description": "Credential for the server.",
          "type": "string"
        },
        "routeType": {
          "$ref": "#/definitions/RouteType"
        }
      }
    },
    "CommunicationRelayConfiguration": {
      "description": "A relay configuration containing the STUN/TURN URLs and credentials.",
      "required": [
        "expiresOn",
        "iceServers"
      ],
      "type": "object",
      "properties": {
        "expiresOn": {
          "format": "date-time",
          "description": "The date for which the username and credentials are not longer valid. Will be 48 hours from request time.",
          "type": "string"
        },
        "iceServers": {
          "description": "An array representing the credentials and the STUN/TURN server URLs for use in ICE negotiations.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/CommunicationIceServer"
          }
        }
      }
    },
    "RouteType": {
      "description": "The routing methodology to where the ICE server will be located from the client. \"any\" will have higher reliability while \"nearest\" will have lower latency. It is recommended to default to use the \"any\" routing method unless there are specific scenarios which minimizing latency is critical.",
      "enum": [
        "any",
        "nearest"
      ],
      "type": "string",
      "x-ms-enum": {
        "name": "RouteType",
        "modelAsString": true
      }
    }
  },
  "parameters": {
    "ApiVersionParameter": {
      "in": "query",
      "name": "api-version",
      "description": "Version of API to invoke.",
      "required": true,
      "enum": [
        "2022-02-01"
      ],
      "type": "string"
    }
  },
  "securityDefinitions": {
    "azure_auth": {
      "type": "oauth2",
      "flow": "implicit",
      "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
      "scopes": {
        "user_impersonation": "impersonate your user account"
      }
    }
  },
  "x-ms-parameterized-host": {
    "hostTemplate": "{endpoint}",
    "useSchemePrefix": false,
    "parameters": [
      {
        "name": "endpoint",
        "description": "The communication resource, for example https://my-resource.communication.azure.com",
        "required": true,
        "type": "string",
        "in": "path",
        "x-ms-skip-url-encoding": true,
        "x-ms-parameter-location": "client"
      }
    ]
  }
}