Use portals Web API write, update, and delete operations

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 a single property value

Operation Method URI
Delete a single property 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

Add a reference to a collection-valued navigation property

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)

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

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

Change the reference in a single-valued navigation property

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.

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

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.

Associate tables on update by using a 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);
		}
  });

Next step

Tutorial: Use portal Web API

See also

Portals Web API overview
Portals read operations using the Web API