Dataverse Web API Tip #5: Direct Single-Property Access

If all you’re interested in is working with a single column value from a single table row, you can reference the property of interest directly by name (no need to append a query string with a $select in it, like ?$select=firstname):

GET {{webapiurl}}contacts(b8d3f910-1896-eb11-b1ac-000d3a3ac80d)/firstname
(include the "always include" headers)

If the property of interest is not null, you’ll receive a JSON object in response along the lines of the following, with the requested value in value:

{
  "@odata.context": "{{webApiUrl}}$metadata#contacts(b8d3f910-1896-eb11-b1ac-000d3a3ac80d)/firstname",
  "value": "Yvonne"
}

This response can be streamlined. If all you want is a rendering of the specified property’s value instead of a formal JSON object, you can instruct the API to return just that appending /$value to the URL:

GET {{webapiUrl}}contacts(b8d3f910-1896-eb11-b1ac-000d3a3ac80d)/firstname/$value
(include the "always include" headers)

Yvonne

(Be aware that /$value‘s textual output is not produced using JSON rules so its format may not match what the first approach returned. For example, imagine fetching a datetime property using both approaches described above. The JSON response might look like "value":"2021-04-09T13:56:42Z" while for the same property the /$value response might be 4/9/2021 1:56:42 PM +00:00.)

Null Values

With both request styles, if the requested property’s value is null, a 204 No Content response will be returned.

GET {{webapiurl}}contacts(b8d3f910-1896-eb11-b1ac-000d3a3ac80d)/address1_line1
(include the "always include" headers) 

-- returns 204 if address1_line1 is null
GET {{webapiurl}}contacts(b8d3f910-1896-eb11-b1ac-000d3a3ac80d)/address1_line1/$value
(include the "always include" headers)

-- returns 204 if address1_line1 is null

Update & Delete

You can use this direct column reference approach to update a value, as well, using either PATCH or PUT:

Request: PATCH {{webApiUrl}}contacts(b8d3f910-1896-eb11-b1ac-000d3a3ac80d))/firstname
(include the "always include" headers)

Body: { "value": "new value for the first name field goes here" }

Or

Request: PUT {{webApiUrl}}contacts(b8d3f910-1896-eb11-b1ac-000d3a3ac80d))/firstname
(include the "always include" headers)

Body: { "value": "new value for the first name field goes here" }

Clearing the field’s value (i.e. setting it to null) is even easier. Simply send a DELETE request with no body:

DELETE {{webapiurl}}contacts(b8d3f910-1896-eb11-b1ac-000d3a3ac80d))/firstname
(include the "always include" headers)

Note: The /$value shortcut applies only to GET requests; not PATCH, PUT or DELETE.

Note

Don’t forget to include the “always include” headers with every request sent to the Web API.

Leave a Reply

Your email address will not be published. Required fields are marked *