Perform basic data operations using the OData endpoint

  • Article

 

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

In This Topic

Creating records

  • Using ATOM

  • Using JSON

Retrieving records

  • Using ATOM

  • Using JSON

Updating records

  • Update using PUT

  • Update using MERGE

    • Using ATOM

    • Using JSON

Deleting records

  • Using ATOM

  • Using JSON

HTTP status codes

Creating records

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.

Using ATOM

For example, when a new account record is created by using System.Data.Services.Client library in managed code

HTTP request

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="https://schemas.microsoft.com/ado/2007/08/dataservices" 
xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
xmlns="http://www.w3.org/2005/Atom">
  <category 
   scheme="https://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 response

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="https://schemas.microsoft.com/ado/2007/08/dataservices" 
xmlns:m="https://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="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" 
  />
  <content type="application/xml">
    <m:properties>
[Properties removed for brevity]
</m:properties>
  </content>
</entry>

In This Topic

Using JSON

For example, when a new account record is created by using the XMLHttpRequest object from the browser.

HTTP request

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 response

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]
 }
}

In This Topic

Retrieving records

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.

In This Topic

Using ATOM

For example, when you are retrieving a single account record using System.Data.Services.Client library in managed code.

HTTP request

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 response

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="https://schemas.microsoft.com/ado/2007/08/dataservices" 
   xmlns:m="https://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="https://schemas.microsoft.com/ado/2007/08/dataservices/scheme" 
  />
  <content type="application/xml">
    <m:properties>
[Properties removed for brevity]
    </m:properties>
  </content>
</entry>

In This Topic

Using JSON

For example, when you are retrieving an account record using the XMLHttpRequest object from the browser.

HTTP request

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>

HTTP response

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 This Topic

Updating records

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.

Update using PUT

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

Update using MERGE

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.

In This Topic

Using ATOM

For example, when updating an account record using System.Data.Services.Client library in managed code:

HTTP request

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="https://schemas.microsoft.com/ado/2007/08/dataservices" 
   xmlns:m="https://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
   xmlns="http://www.w3.org/2005/Atom">
  <category 
   scheme="https://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 response

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

In This Topic

Using JSON

For example, when updating an account record using the XMLHttpRequest object from the browser.

HTTP request

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 response

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

Deleting records

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.

In This Topic

Using ATOM

For example, when you delete an account record using System.Data.Services.Client library in managed code.

HTTP request

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 response

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

In This Topic

Using JSON

For example, when you delete an account record using the XMLHttpRequest object from the browser.

HTTP request

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 response

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

In This Topic

HTTP status codes

Details about HTTP status codes returned are available in OData endpoint Http status codes.

See Also

Use the OData endpoint with web resources
Perform additional data operations using the OData endpoint
Use the OData endpoint with Ajax and JScript web resources
OData endpoint Http status codes

© 2016 Microsoft. All rights reserved. Copyright