- The Web API, which is new for Microsoft Dynamics 365 (online & on-premises), provides a development experience that can be used across a wide variety of programming languages, platforms, and devices.
- The Web API implements the OData (Open Data Protocol), version 4.0, an OASIS standard for building and consuming RESTful APIs over rich data sources.
- The Web API will provide parity with the existing organization service (SOAP endpoint).
- You can perform all operations using HTTP requests with the Web API located at [organization Uri]/api/data/v8.0/.
Understanding XMLHttpRequest:
- When you use the Web API will use an XMLHttpRequest object. XMLHttpRequest (XHR) is a native object found in all modern browsers, and it enables AJAX techniques to make webpages dynamic. Although the name of the object contains “XML,” all requests using the Web API will use JSON rather than XML.
- All modern browsers have a standard XMLHttpRequest implementation, you don’t need a separate library to mitigate these differences.
- If you will perform Web API requests in form scripts or ribbon commands, we recommend that you use the XMLHttpRequest directly and not take a dependency on jQuery.
CRUD Operations using web API:
There are different HTTP request methods for CRUD operations:
Create: POST.
Retrieve: GET.
Update: PATCH- This method is used to update multiple property of particular entity type.
Delete: DELETE.
1. Create Request Using Web API :
Create a custom entity “new_testentity” using the Web API and the XMLHttpRequest object.
Code Explanation:
After you initialize the XMLHttpRequest object, you have to open it before you can set properties or send it.
We need to set the URL to match the entity set path for the TestEntity EntityType. The full URL in this example is clientURL + "/api/data/v8.1/ new_testentities" and the clientURL variable must be set to root URL of the Microsoft Dynamics 365 application.
The clientURL we can get using context object i.e. Xrm.Page.context.getClientUrl ();
After you open the XMLHttpRequest you can apply a number of request headers using the setRequestHeader method.
We need to capture the moment that the XMLHttpRequest completes, you must set an event handler to the onreadystatechange property to detect when the readystate property equals 4, which indicates complete. At that time you can examine the status property.
You can examine the status property to determine whether the operation was successful. In this case, the expected status value is 204 No Content because nothing is expected in the body of the response from a create operation.
The URI for the new_testentity created is in the OData-EntityId header and can be accessed using the getResponseHeadermethod.
If this was a different operation that was expected to return data in the response, it would have a 200 OK status value and the function would use JSON.parse on the XMLHttpRequest response to convert the JSON response into a JavaScript object that your code could access.
Finally, use the XMLHttpRequestsend method to send the request, including any JSON data required. Use JSON.stringifyto convert JavaScript objects to JSON strings that can be included in the body of the request when you send it.
To set the lookup (single-valued) navigation property we can use two options, like following
"new_Contact@odata.bind": "/contacts(63A0E5B9-88DF-E311-B8E5-6C3BE5A8B200)",
In above code, we are setting new_contact using existing contact record, but if required we can also create contact record on the fly and set lookup using following option:
"new_Contact": { "firstname": "b2", "lastname": "test12" },
2. Retrieve Request Using Web API:
Use a GET request to retrieve data for an entity specified as the resource with a unique identifier. When retrieving an entity you can also request specific properties and expand navigation properties to return properties from related entities.
The above example will return all the properties for account record, which is against the performance best practices for retrieving data. This example was just to illustrate how you can do a basic retrieve of an entity instance in Dynamics 365.
Use the $select system query option to limit the properties returned by including a comma-separated list of property names. This is an important performance best practice. If properties aren’t specified using $select, all properties will be returned.
req.open("GET", encodeURI(ClientURL + "/api/data/v8.2/new_testentities?$select=new_name,new_optionset,new_datetime", true));
When you only need to retrieve the value of a single property for an entity, you can append the name of the property to the URI for an entity to return only the value for that property.
req.open("GET", encodeURI(ClientURL + /api/data/v8.2/new_testentities(FEF6F7A7-0B0F-E711-813B-C4346BDD31A1)/new_name",true));
In the same way that you can retrieve individual property values, you can also access the values of navigation properties (lookup fields) by appending the name of the navigation property to the URI referencing an individual entity.
req.open("GET", encodeURI(ClientURL + /api/data/v8.2/new_testentities(FEF6F7A7-0B0F-E711-813B-C4346BDD31A1 /new_Account?$select=name",true));
3. Update Request Using Web API:
Update operations use the HTTP PATCH verb. Pass a JSON object containing the properties you want to update to the URI that represents the entity. A response with a status of 204 will be returned if the update is successful.
When updating an entity, only include the properties you are changing in the request body. Simply updating the properties of an entity that you previously retrieved, and including that JSON in your request, will update each property even though the value is the same.
When you want to update only a single property value use a PUT request with the property name appended to the Uri of the entity.
4. Delete Request Using Web API:
To delete the value of a single property use a DELETE request with the property name appended to the Uri of the entity.
But if we want to remove single-valued navigation (lookup) we need to pass the single-values navigation property name and also need to append “$ref” like below:
req.open("DELETE", encodeURI(ClientURL + "/api/data/v8.2/new_testentities(" + GUIDvalue + ")/new_Account/$ref", true));
Above request will remove the lookup value form the record which means association between these records will be removed.
And finally to delete complete record we can just simply pass complete record URI like below:
