Share via

Azure Digital Twins Swagger reference documentation

  • Article

Important

A new version of the Azure Digital Twins service has been released. In light of the new service's expanded capabilities, the original Azure Digital Twins service (described in this documentation set) has been retired.

To view the documentation for the new service, visit the active Azure Digital Twins Documentation.

Each provisioned Azure Digital Twins instance includes its own automatically generated Swagger reference documentation.

Swagger, or OpenAPI, unites complex API information into an interactive and language-agnostic reference resource. Swagger provides critical reference material about which JSON payloads, HTTP methods, and specific endpoints to use to perform operations against an API.

Swagger summary

Swagger provides an interactive summary of your API, which includes:

  • API and object model information.
  • REST API endpoints that specify the required request payloads, headers, parameters, context paths, and HTTP methods.
  • Testing of API functionalities.
  • Example response information used to validate and confirm HTTP responses.
  • Error code information.

Swagger is a convenient tool to assist with development and testing calls made to the Azure Digital Twins Management APIs.

Tip

A Swagger sneak preview is provided to demonstrate the API feature set. It's hosted at docs.westcentralus.azuresmartspaces.net/management/swagger.

You can access your own generated Management API Swagger documentation at:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
Name Replace with
YOUR_INSTANCE_NAME The name of your Azure Digital Twins instance
YOUR_LOCATION Which server region your instance is hosted on

Reference material

The automatically generated Swagger reference material supplies a quick overview of important concepts, available Management API endpoints, and a description of each object model to assist development and testing.

A concise summary describes the API.

Swagger summary and API overview information

Management API object models are also listed.

Swagger models listed at bottom of Swagger UI

You can select each listed object model for a more detailed summary of key attributes.

Swagger models expanded to read the contents of models

The generated Swagger object models are convenient to read all available Azure Digital Twins objects and APIs. Developers can use this resource when they build solutions on Azure Digital Twins.

Endpoint summary

Swagger also provides a thorough overview of all endpoints that compose the Management APIs.

Each listed endpoint also includes the required request information, such as the:

  • Required parameters.
  • Required parameter data types.
  • HTTP method to access the resource.

Swagger endpoints displayed in Swagger UI

Select each resource to display their additional contents to get a more detailed overview.

Use Swagger to test endpoints

One of the powerful functionalities Swagger provides is the ability to test an API endpoint directly through the documentation UI.

After you select a specific endpoint, the Try it out button will be displayed.

Swagger Try it out button

Expand that section to bring up input fields for each required and optional parameter. Enter the correct values, and select Execute.

Swagger Try it out result example

After you execute the test, you can validate the response data.

Swagger response data

Each listed endpoint also includes response body data to validate your development and tests. These examples include the status codes and JSON for successful HTTP requests.

Swagger JSON response example

The examples also include error codes to help debug or improve failing tests.

Swagger OAuth 2.0 authorization

Note

  • The user principal that created the Azure Digital Twins resource will have a Space Administrator role assignment and will be able to create additional role assignments for other users. Those users and their roles can be authorized to call the APIs.

  1. Follow the steps in the Quickstart to create and configure an Azure Active Directory application. Alternatively, you can reuse an existing app registration.

  2. Add the following Redirect URI to your Azure Active Directory app registration:

    Register Swagger redirect url in AAD

    https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
    Name Replace with Example
    YOUR_SWAGGER_URL Your Management REST API documentation URL found in the portal https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger

  3. Select the Implicit grant > Access tokens check box to allow the OAuth 2.0 implicit grant flow to be used. Select Configure, then Save.

  4. Copy the Client ID of your Azure Active Directory app.

After completing the Azure Active Directory registration:

  1. Select the Authorize button on your swagger page.

    Select the Swagger authorize button

  2. Paste the application ID into the client_id field.

    Swagger client_id field

  3. You will then be redirected to the following success modal.

    Swagger redirect modal

To learn more about interactively testing requests protected by OAuth 2.0, read the official documentation.

Next steps