Azure Digital Twins Swagger reference documentation
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) will be retired by the end of year 2020.
To view the documentation for the new service, visit the active Azure Digital Twins Preview 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 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.
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:
|YOUR_INSTANCE_NAME||The name of your Azure Digital Twins instance|
|YOUR_LOCATION||Which server region your instance is hosted on|
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.
Management API object models are also listed.
You can select each listed object model for a more detailed summary of key attributes.
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.
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.
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.
Expand that section to bring up input fields for each required and optional parameter. Enter the correct values, and select Execute.
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.
The examples also include error codes to help debug or improve failing tests.
Swagger OAuth 2.0 authorization
- 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.
Follow the steps in the Quickstart to create and configure an Azure Active Directory application. Alternatively, you can reuse an existing app registration.
Add the following Redirect URI to your Azure Active Directory app registration:
Name Replace with Example YOUR_SWAGGER_URL Your Management REST API documentation URL found in the portal
Select the Implicit grant > Access tokens check box to allow the OAuth 2.0 implicit grant flow to be used. Select Configure, then Save.
Copy the Client ID of your Azure Active Directory app.
After completing the Azure Active Directory registration:
Select the Authorize button on your swagger page.
Paste the application ID into the client_id field.
You will then be redirected to the following success modal.
To learn more about interactively testing requests protected by OAuth 2.0, read the official documentation.