|
| 1 | +--- |
| 2 | +title: Test and explore the Dataverse Web API |
| 3 | +description: Quickly and conveniently interact with Power Platform web APIs, including the Dataverse Web API in a preauthenticated software testing tool. |
| 4 | +author: denise-msft |
| 5 | +ms.author: demora |
| 6 | +ms.reviewer: matp |
| 7 | +ms.service: powerapps |
| 8 | +ms.topic: how-to |
| 9 | +ms.date: 05/24/2024 |
| 10 | +ms.custom: template-how-to |
| 11 | +contributors: |
| 12 | +- dikamath |
| 13 | +--- |
| 14 | + |
| 15 | +# Explore and test Dataverse in the Web API playground (preview) |
| 16 | + |
| 17 | +[!INCLUDE [cc-beta-prerelease-disclaimer](../../../includes/cc-beta-prerelease-disclaimer.md)] |
| 18 | + |
| 19 | +The API playground is a preauthenticated software testing tool that helps makers quickly and conveniently interact with the [Microsoft Dataverse Web API](/power-apps/developer/data-platform/webapi/overview). |
| 20 | + |
| 21 | + |
| 22 | + |
| 23 | +This web application allows developers to test and experiment with different API endpoints without the need for extensive setup or authentication processes. It also conveniently presents certain available actions and links to documentation for faster learning. |
| 24 | + |
| 25 | +Use this tool to explore what's possible in the RESTful API, test user-defined workflows, and more. |
| 26 | + |
| 27 | +> [!IMPORTANT] |
| 28 | +> |
| 29 | +> - This is a preview feature. |
| 30 | +> - [!INCLUDE [cc-preview-features-definition](../../../includes/cc-preview-features-definition.md)] |
| 31 | +
|
| 32 | +## Key features |
| 33 | + |
| 34 | +- Preauthenticated: The API playground comes preauthenticated, so developers can start testing and experimenting with API endpoints right away. |
| 35 | +- Web-based: With the API playground, developers can quickly interact with the Dataverse Web API without the need for extensive setup like software downloads or non-Microsoft account setup. You can access the tool from the Dataverse accelerator, a Microsoft app available in all new Dataverse environments and can be installed in any environment. |
| 36 | +- Convenient: Presents the various actions and capabilities available in the Dataverse Web API, making it easy to quickly learn what's possible and how to implement it. |
| 37 | + |
| 38 | +## Prerequisites |
| 39 | + |
| 40 | +You must have [access to Dataverse](/power-apps/maker/data-platform/data-platform-entity-licenses), and [access to play the Dataverse accelerator app](./dataverse-accelerator.md#prerequisites-to-run-the-dataverse-accelerator). Members of the system customizer security role have access to play the app. |
| 41 | + |
| 42 | +## Get started |
| 43 | + |
| 44 | +To get started with the API playground, [play](dataverse-accelerator.md#play-the-dataverse-accelerator) the Dataverse accelerator and go to the **API playground** page. |
| 45 | + |
| 46 | + |
| 47 | + |
| 48 | +### Make requests to the Dataverse Web API |
| 49 | + |
| 50 | +On the landing screen, choose the request type to open the request editor by selecting **Create** on any of the top cards. |
| 51 | + |
| 52 | +Three request types are presented: |
| 53 | + |
| 54 | +| Type | Description | |
| 55 | +|-|-| |
| 56 | +| Custom API | This includes any Dataverse Web API [actions](/power-apps/developer/data-platform/webapi/use-web-api-actions), [functions](/power-apps/developer/data-platform/webapi/use-web-api-functions) from Microsoft, or any public [user-defined custom APIs](/power-apps/developer/data-platform/custom-api) registered in the working environment. | |
| 57 | +| Instant plug-in | [Instant plug-ins](/power-apps/maker/data-platform/low-code-plug-ins?tabs=instant) are classified as any user-defined workflows registered as a custom API in the environment with a related FxExpression. | |
| 58 | +| OData request | Allows more granular control over the request inputs to send [OData requests](/power-apps/developer/data-platform/webapi/perform-operations-web-api). | |
| 59 | + |
| 60 | +### Request a custom API or instant plug-in |
| 61 | + |
| 62 | +These request types are designed to simplify calling plug-ins available in the working environment. |
| 63 | + |
| 64 | +1. Select an option from the main dropdown list, which presents the available plug-ins in the current environment. |
| 65 | + :::image type="content" source="media/api-play-list-customapi.svg" alt-text="Custom APIs are listed in the dropdown list" lightbox="media/api-play-list-customapi.svg"::: |
| 66 | + |
| 67 | +1. If parameters are available, they're displayed in the **Query params** table that appears. Provide values for required parameters. |
| 68 | + :::image type="content" source="media/api-play-customapi-params.svg" alt-text="Custom API parameters display automatically" lightbox="media/api-play-customapi-params.svg"::: |
| 69 | + |
| 70 | + > [!NOTE] |
| 71 | + > Checkboxes to the left of each parameter indicate whether they are included in the request. Required parameters have disabled checkboxes while optional parameters have editable ones. |
| 72 | +
|
| 73 | +1. Select **Send**. |
| 74 | + |
| 75 | +1. Observe the [response](#view-the-response) in the lower section of the screen. |
| 76 | + :::image type="content" source="media/api-play-response.svg" alt-text="Parameters are listed if registered" lightbox="media/api-play-response.svg"::: |
| 77 | + |
| 78 | +> [!NOTE] |
| 79 | +> The interface provides a convenient listing of all available plug-ins in the environment. When selected, the associated parameters with data types are presented. Behind the scenes an OData call is still being made, but the interface simplifies the construction of the call. |
| 80 | +
|
| 81 | +### Make an OData request |
| 82 | + |
| 83 | +OData requests allow more options for request parameters. |
| 84 | + |
| 85 | +1. Select the **HTTP request method** in the first dropdown list. |
| 86 | + |
| 87 | +1. Type in the *endpoint Url*. Only include the request URL after `[OrgUrl]/api/data/v9.2/` |
| 88 | + |
| 89 | +1. Add *query parameters* using one of the two methods: |
| 90 | + |
| 91 | + 1. In the URL. |
| 92 | + 1. After the question mark (`?`) character in the URL, type in the query parameter key. |
| 93 | + :::image type="content" source="./media/api-play-key.svg" alt-text="Key typed into Url after question mark" lightbox="./media/api-play-key.svg"::: |
| 94 | + |
| 95 | + 1. Type an equals (`=`) character after the key. |
| 96 | + 1. Type in the value. |
| 97 | + :::image type="content" source="./media/api-play-value.svg" alt-text="Value typed into Url after the equals sign" lightbox="./media/api-play-value.svg"::: |
| 98 | + |
| 99 | + The keys and values will automatically populate the parameter table in the interface. |
| 100 | + |
| 101 | + 1. Manually add query parameters by selecting **+ Add param**. This adds an empty parameter row to the table that you can type values into. The URL is updated dynamically as values are entered. |
| 102 | + |
| 103 | +1. Optionally provide a body (if using all request methods except GET) by selecting the **Body** tab, and then enter the body value in the editor control. |
| 104 | +1. Select **Send**. |
| 105 | +1. Observe the [response](#view-the-response) in the lower section. |
| 106 | + |
| 107 | +### View the response |
| 108 | + |
| 109 | +After a request is sent, the response is displayed in the lower half of the screen. |
| 110 | + |
| 111 | +:::image type="content" source="media/api-play-odata-response.svg" alt-text="OData response" lightbox="media/api-play-odata-response.svg"::: |
| 112 | + |
| 113 | +The response status provides quick metrics on the request: |
| 114 | + |
| 115 | +- Status message |
| 116 | +- Duration (in milliseconds) |
| 117 | +- Size (in kilobytes) |
| 118 | + |
| 119 | +The response body is displayed below the response status. Select the copy icon to copy the response body to your clipboard. |
| 120 | + |
| 121 | +### Save an API request |
| 122 | + |
| 123 | +You can save requests for quick access later. Saved requests store the request details, such as the request method and endpoint for OData request, or the selected plug-in for custom API and instant plug-in, and the input parameters with associated values. |
| 124 | + |
| 125 | +1. In the request screen, select **Save** in the top right corner of the page. |
| 126 | + |
| 127 | + A dialog appears with form fields. |
| 128 | +1. Provide a name for the request. A default value is provided based on the request details, but you can update the value. |
| 129 | + :::image type="content" source="./media/api-play-save.svg" alt-text="Save request dialog" lightbox="./media/api-play-save.svg"::: |
| 130 | + |
| 131 | +1. Select **Save**. |
| 132 | +1. The saved request appears in the left pane of the screen. |
| 133 | + :::image type="content" source="media/api-play-saved-requests.svg" alt-text="Save requests appear in the left pane of the screen" lightbox="media/api-play-saved-requests.svg"::: |
| 134 | + |
| 135 | +### Load a saved request |
| 136 | + |
| 137 | +To load a saved request, select a request name. This loads the request screen with the request details filled in, including input parameters and values. |
| 138 | + |
| 139 | +> [!NOTE] |
| 140 | +> You can only view saved requests that you've created. |
| 141 | +
|
| 142 | +## FAQs |
| 143 | + |
| 144 | +### What privileges are required to access the API playground tool? |
| 145 | + |
| 146 | +You must have access to the Dataverse accelerator app to use the tool. |
| 147 | + |
| 148 | +### Does the API playground tool only connect to the Dataverse Web API? |
| 149 | + |
| 150 | +Yes, the API playground tool only connects to the Dataverse Web API. No other services are available to connect to in this interface. |
| 151 | + |
| 152 | +### How does the API playground tool authenticate to the Dataverse Web API? |
| 153 | + |
| 154 | +The tool uses the authentication token of the logged in user that is required to play the Dataverse accelerator application. |
| 155 | + |
| 156 | +### Is the API playground feature available in all environments? |
| 157 | + |
| 158 | +The feature is delivered through the Dataverse accelerator and is available in all environments that have the app installed. The app is automatically installed in all new environments, but can also be installed in older environments by following the [install instructions](dataverse-accelerator.md#install-the-dataverse-accelerator). |
| 159 | + |
| 160 | +## See also |
| 161 | + |
| 162 | +[Get preview features early with the Dataverse accelerator (preview)](dataverse-accelerator.md) |
0 commit comments