Use portals Web API write, update, and delete operations

Article
03/02/2023

You can perform available Web API operations in portals. Web API operations consist of HTTP requests and responses. This article provides sample write, update, and delete operations, methods, URI, and sample JSON you can use in the HTTP requests.

Important

Your portal version must be 9.3.3.x or later for this feature to work.

Prerequisites

Enable table and field for Web API operations. More information: Site settings for the Web API
The portals Web API accesses table records and follows the table permissions given to users through the associated web roles. Ensure you configure the correct table permissions. More information: Create web roles

Create a record in a table

Note

When referring to Dataverse tables using the portals Web API, you need to use the EntitySetName, for example, to access the account table, the code syntax will use the EntitySetName of accounts.

Basic create

Operation	Method	URI	JSON Sample
Basic create	POST	[Portal URI]/_api/accounts	{"name":"Sample Account"}

As an example, the following request body posted to the Account table set will create a total of four new tables—including the account—in the context of creating the account.

A contact is created because it's defined as an object property of the single-valued navigation property primarycontactid.
An opportunity is created because it's defined as an object within an array that's set to the value of a collection-valued navigation property opportunity_customer_accounts.
A task is created because it's defined as an object within an array that's set to the value of a collection-valued navigation property Opportunity_Tasks.

{
 "name": "Sample Account",
 "primarycontactid":
 {
     "firstname": "Alton",
     "lastname": "Stott"
 },
 "opportunity_customer_accounts":
 [
  {
      "name": "Opportunity associated to Sample Account",
      "Opportunity_Tasks":
      [
       { "subject": "Task associated to opportunity" }
      ]
  }
 ]
}

Associate table records on create

Operation	Method	URI	JSON Sample
Associate table records on create	POST	[Portal URI]/_api/accounts	`{"name":"Sample Account","primarycontactid@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"}`

Sample JSON for creating an annotation via the Web API

{
    "new_attribute1": "test attribute 1",
    "new_attribute2": "test attribute 2",
    "new_comments": "test comments",
    "new_recordurl": recordURL,
    "new_feedback_Annotations":
        [
            {
                "notetext": "Screenshot attached",
                "subject": "Attachment",
                "filename": file.name,
                "mimetype": file.type,
                "documentbody": base64str,
            }
        ]
    }

documentbody will contain the attachment as a base64 string.

Update and delete records by using the Web API

Basic update

Operation	Method	URI	JSON Sample
Basic update	PATCH	[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000001)	`{ "name": "Updated Sample Account ", "creditonhold": true, "address1_latitude": 47.639583, "description": "This is the updated description of the sample account", "revenue": 6000000, "accountcategorycode": 2 }`

Update a single property value

Operation	Method	URI	JSON Sample
Update a single property value	PUT	[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000001)/name	`{"value": "Updated Sample Account Name"}`

Delete or clear a field value

Operation	Method	URI
Delete or clear a field value	DELETE	[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000001)/description

Basic delete

Operation	Method	URI
Basic delete	DELETE	[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000001)

Associate and disassociate tables by using the Web API

Operation	Method	URI	JSON Sample
Add a reference to a collection-valued navigation property	POST	[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000002)/opportunity_customer_accounts/$ref	`{"@odata.id":"[Portal URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)"}`

Remove a reference to a table

Operation	Method	URI
Remove a reference to a table	DELETE	[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000002)/opportunity_customer_accounts/$ref?$id=[Portal URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)

For a single-valued navigation property, remove the $id query string parameter.

Operation	Method	URI
Remove a reference to a table for a single-valued navigation property	DELETE	[Portal URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref

Operation	Method	URI	JSON Sample
Change the reference in a single-valued navigation property	PUT	[Portal URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref	`{"@odata.id":"[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000002)"}`

Associate tables on create

New tables can be created with relationships by using deep insert.

You can associate tables on update by using the same message described in Basic update earlier in this topic, but you must use the @odata.bind annotation to set the value of a single-valued navigation property. The following example changes the account associated to an opportunity by using the customerid_account single-valued navigation property.

Operation	Method	URI	JSON Sample
Associate tables on update by using a single-valued navigation property	PATCH	[Portal URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)	`{"customerid_account@odata.bind":"[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000002)"}`

Web API AJAX samples

This sample demonstrates how to create, update, and delete table records by using Asynchronous JavaScript and XML (AJAX).

Wrapper AJAX function

	(function(webapi, $){
		function safeAjax(ajaxOptions) {
			var deferredAjax = $.Deferred();
	
			shell.getTokenDeferred().done(function (token) {
				// add headers for AJAX
				if (!ajaxOptions.headers) {
					$.extend(ajaxOptions, {
						headers: {
							"__RequestVerificationToken": token
						}
					}); 
				} else {
					ajaxOptions.headers["__RequestVerificationToken"] = token;
				}
				$.ajax(ajaxOptions)
					.done(function(data, textStatus, jqXHR) {
						validateLoginSession(data, textStatus, jqXHR, deferredAjax.resolve);
					}).fail(deferredAjax.reject); //AJAX
			}).fail(function () {
				deferredAjax.rejectWith(this, arguments); // on token failure pass the token AJAX and args
			});
	
			return deferredAjax.promise();	
		}
		webapi.safeAjax = safeAjax;
	})(window.webapi = window.webapi || {}, jQuery)

Create

	webapi.safeAjax({
		type: "POST",
		url: "/_api/accounts",
		contentType: "application/json",
		data: JSON.stringify({
			"name": "Sample Account"
		}),
		success: function (res, status, xhr) {
      //print id of newly created table record
			console.log("entityID: "+ xhr.getResponseHeader("entityid"))
		}
	});

Update

  webapi.safeAjax({
    type: "PATCH",
    url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
    contentType: "application/json",
    data: JSON.stringify({
      "name": "Sample Account - Updated"
    }),
    success: function (res) {
      console.log(res);
    }
  });

Delete

	webapi.safeAjax({
		type: "DELETE",
		url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
		contentType: "application/json",
		success: function (res) {
			console.log(res);
		}
  });

Associate

The following example will assign an existing contact as the primary contact for an existing account.

var record = {};
record[primarycontactid@odata.bind] = "/contacts(00000000-0000-0000-0000-000000000002)"; 

webapi.safeAjax({
  type: "PATCH",
  contentType: "application/json",
  url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
  data: JSON.stringify(record),
    success: function (data, textStatus, xhr) {
      console.log("Record updated");
    }
});

Next step

How to: Use portal Web API

Use portals Web API write, update, and delete operations

Prerequisites

Create a record in a table

Basic create

Associate table records on create

Sample JSON for creating an annotation via the Web API

Update and delete records by using the Web API

Basic update

Update a single property value

Delete or clear a field value

Basic delete

Associate and disassociate tables by using the Web API

Add a reference to a collection-valued navigation property

Remove a reference to a table

Remove a reference to a table for a single-valued navigation property

Change the reference in a single-valued navigation property

Associate tables on create

Associate tables on update by using a single-valued navigation property

Associate tables on update by using a single-valued navigation property

Web API AJAX samples

Wrapper AJAX function

Create

Update

Delete

Associate

Next step

See also

Feedback

Additional resources

Use portals Web API write, update, and delete operations

Prerequisites

Create a record in a table

Basic create

Sample JSON for creating related table records in one operation

Associate table records on create

Sample JSON for creating an annotation via the Web API

Update and delete records by using the Web API

Basic update

Update a single property value

Delete or clear a field value

Basic delete

Associate and disassociate tables by using the Web API

Add a reference to a collection-valued navigation property

Remove a reference to a table

Remove a reference to a table for a single-valued navigation property

Change the reference in a single-valued navigation property

Associate tables on create

Associate tables on update by using a single-valued navigation property

Associate tables on update by using a single-valued navigation property

Web API AJAX samples

Wrapper AJAX function

Create

Update

Delete

Associate

Next step

See also

Feedback

Additional resources