Portals Web API overview

The portals Web API enables a richer user experience inside Power Pages sites. You can use the Web API to perform create, read, update, and delete operations across all Microsoft Dataverse tables from your webpages. For example, you can create a new account or update a contact without using a form or multistep form by using the portals Web API.

The Web API uses the /_api route (for example, https://yoursite.powerappsportals.com/_api/accounts) and follows a RESTful pattern similar to the Dataverse Web API.

Important

• The portals Web API is built for creating a rich user experience inside portal pages. It isn't optimized for third-party services or application integration. Using the portals Web API to integrate with other Power Pages sites isn't supported.
• Portals Web API operations are limited to tables related to data—for example, accounts, contacts, or your custom tables. Configuring table metadata or portal configuration table data—for example, configuring portals tables such as adx_contentsnippet, adx_entityform, or adx_entitylist—isn't supported by using the portals Web API. For a complete list, see unsupported configuration tables later in this article.
• The portals Web API benefits from server-side caching, so subsequent calls to the Web API are faster than the initial calls. Clearing the portal server-side cache causes temporary performance degradation.
• Portals Web API operations require a Power Pages license. For example, Web API calls made by anonymous users count towards the anonymous user capacity. Web API calls made by authenticated users (internal or external) don't count towards page views, but require applicable authenticated user capacity licenses. For more information, see Power Pages licensing FAQs.
• Calling actions and functions by using the portals Web API isn't supported.

Web API operations

The portals Web API offers a subset of capabilities for Dataverse operations that you can do by using the Dataverse API. The API format is as similar as possible to reduce the learning curve.

Note

Web API operations are case-sensitive.

Web API operations available in Power Pages

• Read records from a table
• Create a record in a table
• Update and delete records in a table
• Associate and disassociate tables

Site settings for the Web API

Important

Support for the wildcard value (*) in the Webapi/<table-name>/fields site setting is deprecated.

Replace * with a comma-separated list of the columns required by your site. Power Pages Web API requests for tables configured with * fail until you configure explicit column names.

To enable the portals Web API for your site, configure the site settings for each table that you want to expose. You can define the columns available to the Web API by listing them in a site setting, by using a Dataverse system view, or by combining both methods.

Note

Use the table logical name for these settings (for example, account).

Site setting name	Description
Webapi/<table-name>/enabled	Enables or disables the Web API for <table name>. Default: False Valid values: True, False
Webapi/<table-name>/fields	Defines a comma-separated list of column logical names available through the Web API. For example, name,accountnumber,telephone1. This setting is required unless Webapi/<table-name>/UseFieldsFromView is set to True and the configured system view contains at least one eligible column. The wildcard value (*) is deprecated.
Webapi/<table-name>/UseFieldsFromView	When set to True, makes columns from a Dataverse system view named Power Pages Web API Columns available through the Web API. Default: False. Valid values: True, False. If Webapi/<table-name>/fields is also configured, columns from both sources are combined.
Webapi/error/innererror	Enables or disables InnerError. Default: False Valid values: True, False

For example, to expose the Web API for the Case table where authenticated users can create, update, and delete records for this entity, use the site settings shown in the following table.

Site setting name	Site setting value
Webapi/incident/enabled	true
Webapi/incident/fields	attr1, attr2, attr3

Configure Web API columns by using a system view

By using a system view, makers can manage the columns available through the portal's Web API without maintaining a comma-separated list in a site setting.

1. In Power Pages design studio, open the Data workspace.
2. Select the table, select the Views tab, and then create or edit a public system view.
3. Name the view Power Pages Web API Columns.
4. Add the columns that your site needs to the view, and then save and publish the view.
5. In the Portal Management app, create the Webapi/<table-name>/UseFieldsFromView site setting for the website and set its value to True.
6. Confirm that Webapi/<table-name>/enabled is set to True.

Note

• Only columns from the primary table that are displayed in the view are included. Columns from related tables aren't included. Columns used only for filtering or sorting aren't included unless they're also displayed in the view.
• For lookup columns, use the corresponding OData lookup property in Web API requests. The property name uses the format _<column-logical-name>_value. For example, the primarycontactid lookup column is returned as _primarycontactid_value.
• Changes to the system view can take up to five minutes to become available to the Web API.

If both Webapi/<table-name>/fields and Webapi/<table-name>/UseFieldsFromView are configured, the Web API combines the columns listed in Webapi/<table-name>/fields with eligible columns from the Power Pages Web API Columns system view for that table.

Important

• The Webapi/<table-name>/UseFieldsFromView site setting is available in Power Pages site version 9.8.8.x and later.
• Support for the wildcard value (*) in Webapi/<table-name>/fields is deprecated. Use explicit column names, the Power Pages Web API Columns system view, or both.

Security with the portal Web API

You can configure record-based security for individual records in portals by using table permissions. The portal Web API accesses table (entity) records and follows the table permissions given to users through the associated web role.

You can configure column permissions to further define privileges to individual columns within a table while using the portal Web API.

Authenticating portal Web API requests

You don't need to include an authentication code because the application session manages authentication and authorization. All Web API calls must include a Cross-Site Request Forgery (CSRF) token.

Using EntitySetName

When referring to Dataverse tables by using the portal Web API in your code, use the EntitySetName. To access the account table, for example, the code syntax uses the EntitySetName of accounts; /_api/accounts().

Note

Use the table logical name for site settings (for example, account).

To determine the EntitySetName of specific tables, follow these steps:

1. Go to https://make.powerapps.com

2. Select the Dataverse tab from the side panel and select the table.

3. Select the ... (Commands option), and then choose Advanced, Tools, and Copy set name to copy the EntitySetName of the table to your clipboard.

   

Privacy laws and regulations

All request headers use a contact ID for auditing purposes. For an anonymous user, the value is null.

If audit logging is enabled, a user can see all the audit events in the Office 365 audit log.

More information:
Enable and use activity logging
Export, configure, and view audit log records

Unsupported configuration tables

You can't use Portal Web API for the following configuration tables:

adx_contentaccesslevel

adx_contentsnippet

adx_entityform

adx_entityformmetadata

adx_entitylist

adx_entitypermission

adx_entitypermission_webrole

adx_externalidentity

adx_pagealert

adx_pagenotification

adx_pagetag

adx_pagetag_webpage

adx_pagetemplate

adx_portallanguage

adx_publishingstate

adx_publishingstatetransitionrule

adx_publishingstatetransitionrule_webrole

adx_redirect

adx_setting

adx_shortcut

adx_sitemarker

adx_sitesetting

adx_urlhistory

adx_webfile

adx_webfilelog

adx_webform

adx_webformmetadata

adx_webformsession

adx_webformstep

adx_weblink

adx_weblinkset

adx_webnotificationentity

adx_webnotificationurl

adx_webpage

adx_webpage_tag

adx_webpageaccesscontrolrule

adx_webpageaccesscontrolrule_webrole

adx_webpagehistory

adx_webpagelog

adx_webrole_systemuser

adx_website

adx_website_list

adx_website_sponsor

adx_websiteaccess

adx_websiteaccess_webrole

adx_websitebinding

adx_websitelanguage

adx_webtemplate

Known issues

Users get a CDS error if they invoke a GET Web API request for tables that have multiple levels of one-to-many or many-to-many table permissions when Parental, Contact, or Account scopes add more conditions to the query.

To resolve this issue, use FetchXML in the OData query.

Next step

Query data using portals Web API

Related information

• Compose HTTP requests and handle errors
• Write, update, and delete operations using the Web API
• How to: Use portal Web API