Perform basic data operations using the OData endpoint
Applies To: Dynamics CRM 2015
There are a variety of libraries or technologies that you might use to execute the HTTP requests to perform data operations using the OData endpoint with Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online 2015 Update. This topic describes the format of the low level HTTP requests. Regardless of the library or technology you use, with a Web debugging proxy tool such as Fiddler, you can examine the HTTP traffic and compare the results that you see with the requirements of the OData endpoint. This topic presents examples of the HTTP Requests and Responses captured using Fiddler. Some content in these examples have been edited for brevity and <placeholders> are included where the content would vary based on environmental variables.
For more information about applications that use a specific technology, see: Use the OData endpoint with Ajax and JScript web resources
New records, or entries, are created by executing an HTTP POST request against the URI of the collection where the entry is to be created. The POST request includes the new entry in its body using either ATOM or JSON formats.
The server assigns default values to any properties not specified in the request and returns the result with a ‘Location’ header that contains the URL for the record that was created. The entry title element reflects the primary attribute of the entity. For example, for the account entity the name attribute is the primary attribute. HTTP status code 201 indicates that the record was successfully created.
For more information about an alternative way to create new records in the context of a related record, see c6de9c12-e8e3-4ed5-a6ed-18ade572065f#BKMK_UsingDeepInsert.
For example, when a new account record is created by using System.Data.Services.Client library in managed code
POST <organization root>/xrmservices/2011/organizationdata.svc/AccountSet HTTP/1.1 Accept-Charset: UTF-8 Accept-Language: en-us dataserviceversion: 1.0;NetFx Accept: application/atom+xml,application/xml Content-Type: application/atom+xml maxdataserviceversion: 2.0;NetFx Referer: <The URL to the HTML page > Accept-Encoding: gzip, deflate User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1) Host: <CRM Server> Content-Length: 26629 Connection: Keep-Alive Pragma: no-cache Cookie: <cookie data> Authorization: Negotiate <authentication token> <?xml version="1.0" encoding="utf-8" standalone="yes"?> <entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom"> <category scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" term="Microsoft.Crm.Sdk.Data.Services.Account" /> <title type="text">New Account Created</title> <author> <name /> </author> <updated>2010-07-22T22:51:50.0051481Z</updated> <id /> <content type="application/xml"> <m:properties> [ Properties removed for brevity] </m:properties> </content> </entry>
HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 26756
Content-Type: application/atom+xml;charset=utf-8
Location: <organization root>/XRMServices/2011/OrganizationData.svc/AccountSet(guid'732b64b6-e395-df11-a492-00155dba380c')
Server: Microsoft-IIS/7.0
X-AspNet-Version: 4.0.30319
DataServiceVersion: 1.0;
X-Powered-By: ASP.NET
WWW-Authenticate: Negotiate <authentication token>
Date: Thu, 22 Jul 2010 22:51:49 GMT
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="<organization root>/XRMServices/2011/OrganizationData.svc/"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns="http://www.w3.org/2005/Atom">
<id><organization root>/XRMServices/2011/OrganizationData.svc/AccountSet(guid'732b64b6-e395-df11-a492-00155dba380c')</id>
<title type="text">New Account Created</title>
<updated>2010-07-22T22:51:50Z</updated>
<author>
<name />
</author>
<link rel="edit" title="Account" href="AccountSet(guid'732b64b6-e395-df11-a492-00155dba380c')" />
[Links removed for brevity]
<category
term="Microsoft.Crm.Sdk.Data.Services.Account"
scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"
/>
<content type="application/xml">
<m:properties>
[Properties removed for brevity]
</m:properties>
</content>
</entry>
For example, when a new account record is created by using the XMLHttpRequest object from the browser.
POST <organization root>/XRMServices/2011/OrganizationData.svc/AccountSet HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept-Language: en-us
Referer: <The URL to the HTML page sending the request>
Accept: application/json
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1)
Host: <CRM Server>
Content-Length: 25
Connection: Keep-Alive
Pragma: no-cache
Cookie: <cookie data>
Authorization: Negotiate <authentication token>
{"Name":"Sample Account"}
HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 17720
Content-Type: application/json;charset=utf-8
Location: <organization root>/XRMServices/2011/OrganizationData.svc/AccountSet(guid'5784bd4a-f595-df11-a492-00155dba380c')
Server: Microsoft-IIS/7.0
X-AspNet-Version: 4.0.30319
DataServiceVersion: 1.0;
X-Powered-By: ASP.NET
WWW-Authenticate: Negotiate <authentication token>
Date: Fri, 23 Jul 2010 00:57:40 GMT
{
"d" : {
"__metadata": {
"uri": "<organization root>/XRMServices/2011/OrganizationData.svc/AccountSet(guid'5784bd4a-f595-df11-a492-00155dba380c')",
"type": "Microsoft.Crm.Sdk.Data.Services.Account"
},
[Properties removed for brevity]
}
}
HTTP GET is used when you are retrieving records. When a unique identifier for a specific record is provided, only that record will be retrieved. Otherwise, any system query options that are defined will be applied and up to 50 records will be retrieved that match any system query option filters.
For example, when you are retrieving a single account record using System.Data.Services.Client library in managed code.
GET <organization root>/xrmservices/2011/organizationdata.svc/AccountSet(guid'732b64b6-e395-df11-a492-00155dba380c') HTTP/1.1
Accept-Charset: UTF-8
Accept-Language: en-us
dataserviceversion: 1.0;NetFx
Accept: application/atom+xml,application/xml
maxdataserviceversion: 2.0;NetFx
Referer: <The URL to the HTML page >
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1)
Host: <CRM Server>
Connection: Keep-Alive
Cookie: <cookie data>
Authorization: Negotiate <authentication token>
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 28231
Content-Type: application/atom+xml;charset=utf-8
Server: Microsoft-IIS/7.0
X-AspNet-Version: 4.0.30319
DataServiceVersion: 1.0;
X-Powered-By: ASP.NET
WWW-Authenticate: Negotiate <authentication token>
Date: Thu, 22 Jul 2010 22:51:51 GMT
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="<organization root>/XRMServices/2011/OrganizationData.svc/"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns="http://www.w3.org/2005/Atom">
<id><organization root>/XRMServices/2011/OrganizationData.svc/AccountSet(guid'732b64b6-e395-df11-a492-00155dba380c')</id>
<title type="text">New Account Created </title>
<updated>2010-07-22T22:51:51Z</updated>
<author>
<name />
</author>
<link rel="edit" title="Account" href="AccountSet(guid'732b64b6-e395-df11-a492-00155dba380c')" />
[Links removed for brevity]
<category
term="Microsoft.Crm.Sdk.Data.Services.Account"
scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"
/>
<content type="application/xml">
<m:properties>
[Properties removed for brevity]
</m:properties>
</content>
</entry>
For example, when you are retrieving an account record using the XMLHttpRequest object from the browser.
GET <organization root>/XRMServices/2011/OrganizationData.svc/AccountSet(guid'5784bd4a-f595-df11-a492-00155dba380c') HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept-Language: en-us
Referer: <The URL to the HTML page sending the request>
Accept: application/json
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1)
Host: <CRM Server>
Connection: Keep-Alive
Cookie: <cookie data>
Authorization: Negotiate <authentication token>
GET <organization root>/XRMServices/2011/OrganizationData.svc/AccountSet(guid'5784bd4a-f595-df11-a492-00155dba380c') HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept-Language: en-us
Referer: <The URL to the HTML page sending the request>
Accept: application/json
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1)
Host: <CRM Server>
Connection: Keep-Alive
Cookie: <cookie data>
Authorization: Negotiate <authentication token>
In OData, you can use either the PUT method or the MERGE method to update records. MERGE is used to avoid overloading the meaning of PUT.
A successful update response contains the HTTP status code 204 and returns no content.
Note |
|---|
To set Microsoft Dynamics CRM complex type values to null, set all the properties of the complex type to null. For more information, see c6de9c12-e8e3-4ed5-a6ed-18ade572065f#BKMK_SetComplexTypesToNull. |
Note |
|---|
Some libraries might not include the body of the request when submitting a PUT or MERGE request to the server. As a workaround, OData supports Method Tunneling through Post using the POST HTTP operator. To use Method tunneling, submit a POST HTTP operation and set the X-HTTP-Method header to the HTTP operation that you want to execute. For example, to submit a MERGE request, the HTTP operation should be POST and the X-HTTP-Method HTTP header should be MERGE. |
Important |
|---|
Updating records using PUT replaces the existing record with the data provided. All property values in the record either take the values provided in the request or are set to their default values if they are not included in the request. Links are not replaced. |
Use PUT when you update individual properties. For more information, see c6de9c12-e8e3-4ed5-a6ed-18ade572065f#BKMK_UpdatingIndividualProperties
The typical update logic in Microsoft Dynamics CRM matches the behavior usually defined by using MERGE. Property values included in the request are applied only to those properties. Other property data is not changed.
Important |
|---|
Unless you take steps to mitigate this behavior, when using the proxy classes in managed code to update retrieved entity records MERGE is used and all properties are updated. This is true even if the value of the properties are not changed. This may cause undesirable side-effects when other event driven features, such as workflows or plugins, detect that the property has been updated. Also, auditing will record that the property has been updated. Furthermore, if an entity instance is instantiated rather than being retrieved, all the properties for the entity are returned with the MERGE request. Any properties that are not set in code will be null. These null values overwrite any existing values for the record. You can mitigate this behavior by implementing an event handler for the DataServiceContext ReadingEntity and WritingEntity events. |
For example, when updating an account record using System.Data.Services.Client library in managed code:
POST <organization root>/xrmservices/2011/organizationdata.svc/AccountSet(guid'732b64b6-e395-df11-a492-00155dba380c') HTTP/1.1 Accept: application/atom+xml,application/xml Accept-Language: en-us dataserviceversion: 1.0;NetFx x-http-method: MERGE Accept-Charset: UTF-8 Content-Type: application/atom+xml maxdataserviceversion: 2.0;NetFx Referer: <The URL to the HTML page > Accept-Encoding: gzip, deflate User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1) Host: <CRM Server> Content-Length: 26753 Connection: Keep-Alive Pragma: no-cache Cookie: <cookie data> Authorization: Negotiate <authentication token> <?xml version="1.0" encoding="utf-8" standalone="yes"?> <entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom"> <category scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" term="Microsoft.Crm.Sdk.Data.Services.Account" /> <title type="text">Account updated </title> <author> <name /> </author> <updated>2010-07-22T22:51:51.0053481Z</updated> <id><organization root>/xrmservices/2011/organizationdata.svc/AccountSet(guid'732b64b6-e395-df11-a492-00155dba380c')</id> <content type="application/xml"> <m:properties> [Properties removed for brevity] </m:properties> </content> </entry>
HTTP/1.1 204 No Content Cache-Control: no-cache Content-Length: 0 Server: Microsoft-IIS/7.0 X-AspNet-Version: 4.0.30319 DataServiceVersion: 1.0; X-Powered-By: ASP.NET WWW-Authenticate: Negotiate <authentication token> Date: Thu, 22 Jul 2010 22:51:51 GMT
For example, when updating an account record using the XMLHttpRequest object from the browser.
POST <organization root>/XRMServices/2011/OrganizationData.svc/AccountSet(guid'5784bd4a-f595-df11-a492-00155dba380c') HTTP/1.1 Accept: application/json Accept-Language: en-us Referer: <The URL to the HTML page sending the request> x-http-method: MERGE Content-Type: application/json; charset=utf-8 Accept-Encoding: gzip, deflate User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1) Host: <CRM Server> Content-Length: 117 Connection: Keep-Alive Pragma: no-cache Cookie: <cookie data> Authorization: Negotiate <authentication token> {"Name":"Updated Sample","Telephone1":"555-0123","AccountNumber":"ABCDEFGHIJ","EMailAddress1":"someone1@example.com"}
HTTP/1.1 204 No Content Cache-Control: no-cache Content-Length: 0 Server: Microsoft-IIS/7.0 X-AspNet-Version: 4.0.30319 DataServiceVersion: 1.0; X-Powered-By: ASP.NET WWW-Authenticate: Negotiate <authentication token> Date: Fri, 23 Jul 2010 00:57:41 GMT
Use a POST request with the X-HTTP-METHOD header set to DELETE with a URI reference to the record to be deleted.
Note |
|---|
Although the OData specification indicates that a successful delete operation should return an HTTP status code of 200 (OK), the Microsoft Dynamics CRM implementation returns 204 (No Content). |
For more information, see c6de9c12-e8e3-4ed5-a6ed-18ade572065f#BKMK_AssociatingAndDisassociating.
For example, when you delete an account record using System.Data.Services.Client library in managed code.
POST <organization root>/xrmservices/2011/organizationdata.svc/AccountSet(guid'732b64b6-e395-df11-a492-00155dba380c') HTTP/1.1
Accept: application/atom+xml,application/xml
Accept-Language: en-us
dataserviceversion: 1.0;NetFx
x-http-method: DELETE
Accept-Charset: UTF-8
Content-Type: application/atom+xml
maxdataserviceversion: 2.0;NetFx
Referer: <The URL to the HTML page >
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1)
Host: <CRM Server>
Content-Length: 0
Connection: Keep-Alive
Pragma: no-cache
Cookie: <cookie data>
Authorization: Negotiate <authentication token>
HTTP/1.1 204 No Content Cache-Control: no-cache Content-Length: 0 Server: Microsoft-IIS/7.0 X-AspNet-Version: 4.0.30319 DataServiceVersion: 1.0; X-Powered-By: ASP.NET WWW-Authenticate: Negotiate <authentication token> Date: Thu, 22 Jul 2010 22:51:54 GMT
For example, when you delete an account record using the XMLHttpRequest object from the browser.
POST <organization root>/XRMServices/2011/OrganizationData.svc/AccountSet(guid'5784bd4a-f595-df11-a492-00155dba380c') HTTP/1.1
Accept: application/json
Accept-Language: en-us
Referer: <The URL to the HTML page sending the request>
x-http-method: DELETE
Content-Type: application/json; charset=utf-8
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1)
Host: <CRM Server>
Content-Length: 0
Connection: Keep-Alive
Pragma: no-cache
Cookie: <cookie data>
Authorization: Negotiate <authentication token>
HTTP/1.1 204 No Content Cache-Control: no-cache Content-Length: 0 Server: Microsoft-IIS/7.0 X-AspNet-Version: 4.0.30319 DataServiceVersion: 1.0; X-Powered-By: ASP.NET WWW-Authenticate: Negotiate <authentication token> Date: Fri, 23 Jul 2010 00:57:57 GMT
Details about HTTP status codes returned are available in OData endpoint Http status codes.
© 2016 Microsoft. All rights reserved. Copyright

