Azure Digital Twins Swagger reference 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 see contents of models

The generated Swagger object models are convenient to see 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

To see a more detailed overview, select each resource.

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, you see Try it out.

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 you want to see 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. Such users and their roles can be authorized to call the APIs.
  1. Follow the steps in this quickstart to create and configure an Azure AD application. Alternatively, you can reuse an existing app registration.

  2. Add the following Redirect url to your Azure AD 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. Copy the Client ID of your Azure AD 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, see the official documentation.

Next steps